This directory contains code to make gscdbd, the "Guide Star Catalog Database
Daemon." Gscdbd is designed to be started once then it serves data from then on
to xephem from the Hubble Guide Star Catalog on demand. The data can be on the
system in the form of either of two CD-ROMs or in cached disk files.

The gscdbd listens to an input fifo for position and FOV information. It
locates the corresponding region(s) from the GSC data and generates responses
for all objects found therein to an output fifo. These fifos correspond to
those named by resources DBFIFO and SKYLOCFIFO from xephem, respectively.

The CD-ROM path is opened and closed for each file. Thus, it is safe to 
unmount one disk and remount the other when necessary without having to stop
and restart gscdbd.

Each time a region is read from the CD-ROM the data can be saved to disk in a
more compact form. From then on references to that same region will be satisfied
from this disk cache. In this way, a set of regions can be pulled from the
CD-ROM and the CD-ROM unmounted if desired.

The GSC CD-ROM set supported by gscdbd is called "The Guide Star Catalog Version
1.1" published by the Space Telescope Science Institute. The catalog is on two
CD-ROMs, one each for roughly the northern and southern hemispheres. This GSC
CD-ROM set may be purchased from several places. I got mine from:

	The Astronomical Society of the Pacific
	390 Ashton Avenue
	San Francisco CA  94112
	(415) 337-2624

When ordering from the ASP, consider specifying that you just want the CD-ROMs
themselves because you do not need the supporting software in order to use them
with gscdbd.

    Building gscdbd

Place everything in a directory called gscdbd off the main xephem source.
The source code for gscdbd is resides entirely within this directory; no
special libraries are needed beyond those normally found on UNIX. Unlike
xephem, however, you will need an ANSI C compiler. The included Makefile just
compiles and links the .c files together to form gscdbd.

    Running gscdbd

Run gscdbd with -h to get a usage summary. Basically you must specify four
pathnames:

    the directory where the CD-ROM is mounted; the default is /cdrom.

    the directory in which to keep the disk cache files; the default is cache.

    the pathname of the fifo to which xephem writes when you ask for data from
	the Sky view menu; default is ../fifos/xephem_loc_fifo.

    the pathname of the fifo to which xephem listens for data base objects; the
        default is ../fifos/xephem_db_fifo.

The default fifo paths will be correct if you use the XEphem.ad resource file 
supplied with xephem and run gscdbd from a directory one level deeper than
that which contains the source to xephem. The default CD-ROM mount point,
/cdrom, varies from system to system but this seems pretty common.  These
defaults are near the top of gscdbd.c if you would like to change them.  

    Hints

o After you've started gscdbd, don't forget to turn on the "Open DB Fifo"
  option in the Controls menu for the Objects/Data Base dialog, and the "Send
  pos to LOCFIFO" option in the Fifos menu for the Sky View.
o Remember that most GSC stars are much dimmer than about magnitude 7 so to see
  them the "Faintest Magnitude" scale in the View/Filter... dialog must be set
  at least that dim.
o By default, xephem deletes the database back to the last checkpoint each time
  a database fifo query is generated. Thus, to build up more and more stars you
  must update the checkpoint after each query by using the Delete/"Set
  Checkpoint" menu option in the Data Base dialog.
o Be careful not to start more than one gscdbd at a time :-)
o gscdbd version 1.4 required a change to the format of the .ech cache files.
  The old format had a bug that broke the header of a few regions, including
  n4500/3588.ech. The change is such that some, but not all, files written
  using older versions of gscdbd still work but files written by version 1.4 of
  gscdbd can not be read by older versions of gscdbd.
o The -l option will load the entire contents of one GSC CDROM onto disk in
  .ech format in one operation, then exit. The contents on each CDROM occupies
  approximately 50 MB of disk space in .ech format.


Thank you for trying gscdbd. I'd like to hear what you think.

Elwood Downey
ecdowney@noao.edu
