This directory contains code for a sample internet GSC server daemon process,
gscd. It also contains code for a program, gscload, which can read a CDROM and
save it to a local disk cache or print GSC stars around any region.

===============================================================================
gscd:

Gscd responds to requests for GSC stars on TCP port 7577. This server is
intended for those who wish to support a GSC service in a local domain running
several instances of xephem. This server is *not necessary* if you have the GSC
CDROMs, if the cache *.ech files are locally accessible to xephem, or if you
can connect to an existing live gscd server.

Run "gscd -help" to get a list of all options.

Gscd exits if it finds itself already running locally, ie, on 127.0.0.1.


Gscd may be run as an independent daemon process, or may be run via inetd.
If not used with inetd, messages are written to stderr and are prefixed with a
date stamp of the form M/D/Y H:M:S.

To set up gscd for use with a typical inetd configuration, copy gscd to a
suitable location then add something like the following line to /etc/inetd.conf:

gsc stream tcp nowait nobody /usr/local/bin/gcsd gscd -ivmc /usr/local/gsccache

And add a line as follows to /etc/services:

gsc             7577/tcp

Then restart inetd using:

kill -HUP <pid_of_inetd>

When running gscd via inetd, most gscd error and trace messages are written
using syslog() as facility LOG_LOCAL7 with priority LOG_INFO. On many systems,
this causes gscd messages to be appended to /var/adm/messages (depending on
/etc/syslog.conf).  This can be changed with the following entry in
/etc/syslog.conf:

    # log all messages from the GSC server, which is the local7 service
    local7.*					/var/adm/gscd

If other syslog.conf entries are so general that they too get the messages,
you can turn them off using the "none" level, as in the following example:

    *.=info;*.=notice;local7.none			/var/adm/messages

If local7 is already in use at your site, you change it in the call to
openlog() in gscd.c.


The code in gscd.c is just the network driver/main function. The code that does
the real work accessing the GSC files is in gsc.c in xephem's main source
directory. Hence, the Makefile here will go there if it needs to build gsc.o.

The protocol to gscd is such that the client (xephem) asks the server (gscd)
for stars centered aroung an RA and Dec out to a certain field of view and down
to a certain magnitude limit. The server responds with either an error message
or a count. If the response is a count greater than 0, that many star records
then follow. The connection is opened/closed for each request and responding
star set.

Note that regardless of the field-of-view requested by the client, the server
silently clamps it to be no greater than 5 degrees.

The format of the communications is as follows. All multibyte values are
stored in big-endian order. If there are any questions, see unpackbuf() and
packbuf() near the bottom of gscd.c.

Initial request (client -> server):

    Byte	Meaning

    0		version number
    1-3		2000 RA, 0 .. 2*PI maps to 0 .. (1<<24)
    4-6		2000 Dec, -PI/2 .. PI/2 maps to 0 .. (1<<24)-1
    7-8		field-of-view, 0 .. 2*PI maps to 0 .. (1<<16)-1
    9-10	faint mag, -30..30 maps to 0 .. (1<<16)-1

Ok status reply (server -> client):

    0		0
    1-79	ASCIZ count of star records to follow

or Error status reply (server -> client):

    0		1
    1-79	ASCIZ error message.

Each star record (client -> server):

    0-1		GSC region number, range 1 .. 9537.
    2-3		GSC designation
    4		class: 0=star, 1=stellar or galaxy, 2=blend 3=artifact
    5-7		2000 RA, 0 .. 2*PI maps to 0 .. (1<<24)
    8-10	2000 Dec, -PI/2 .. PI/2 maps to 0 .. (1<<24)-1
    11-12	mag, -30..30 maps to 0 .. (1<<16)-1

===============================================================================
gscload:

This program loads any region of the sphere from CDROM to disk as specified
by the required arguments of RA, Dec, FOV and Mag. Or, it can print all stars
in that region.

To load the entire northern CDROM to disk, use:

    gscload 0 90 194 20

To load the entire southern CDROM to disk, use:

    gscload 0 -90 164 20

The northern disk occupies approximately 86 MB, and takes about 2 hours to load.
The southern occupies some 73 MB and loads in a similar period.
