GSD read-only library for Unix.
===============================

Make
----

The library is maintained using the "mk" script that is part of it.
Maintenance is controlled mainly by the "makefile" file. The "mk"
command is usually given a target for the make command, the target in
turn being defined in "makefile".

% mk build
   This will build the library from source. Each library source file
   will afterwards be accompanied by an object file and a date-stamp
   file .now. The library itself will be in libgsd.a.

   There is another built file, an executable programme gsd_print. This
   is compiled and linked from gsd_print.c and the final object library.

% mk clean
   This will remove transient files, namely the object files and any
   symbolic links needed during build. In the sequence of targets
   build-clean-build the second build will not need to re-compile any
   code, since the date-stamp files still exist an are newer than the
   source files. (The second build will, however, re-create symbolic
   links.)

% mk unbuild
   This will remove transient and built files.

% mk export_source
   This will compile a list of source files in the file
   $EXPORT/filelist. It appends to such a file if it exists. And it
   prepends "gsd/" to each file name. So it is not terribly useful
   outwith an application package.

% mk export
   As export_source, but includes built files as well.

% mk archive
   Create the gsd_source.tar archive that is required before
   a Starlink build or export_source


Different platforms
-------------------

Before any mk command, the environment variable SYSTEM must be set. Use
"alpha_OSF1", "sun4_Solaris", or "sun4" (SunOS 4.x).

All platform-dependencies are in gsd2.h, or rather gsd2_$(SYSTEM).h.
There exist versions for Alpha/OSF1, Sun4/Solaris and Sun4/SunOS(4.x).
They are also prepared for use under VAX/VMS.

gsd2.h initialises unions, which is possible only in ANSI C. This is
a problem on the VAX.



Source files
------------

mk and makefile are for maintenance.

C_ROUTINES are the C source code of the library. This excludes
   gsd_print.c, which does not enter the library but becomes an
   executable.

PUBLIC_INCLUDES are include files needed by applications calling this
   library.

PRIVATE_INCLUDES are include files needed only within the library.

gsd2_nativx.c and gsd2_copya.c have main modules for testing at the ends
   of the files. These are commented out. When uncommented, the .c files
   can be compiled into executables (linking with -lm). nativx will read
   the file TEST_ARRAY.DAT and produce output similar to
   gsd2_nativx.out. copya works without input file and should produce
   output similar to gsd2_copya.out. TEST_ARRAY.DAT was written on a VAX
   with the programme write_test_array.for.

gsd_print.f is just a tutorial file showing how to port Fortran code
   that calls GSD.

gsd_print.c is compiled into the executable gsd_print by the build
   target. This replaces the old GSD_PRINT utility, which was written in
   Fortran and used VAX LIB$ calls.



C routines
----------

The outermost layer of routines is the Fortran binding. This is in
gsd_f77.c. The routines can only be called from Fortran. They share
static external variables amongst themselves (but with no other
routines) to record references to up to 100 open GSD files. The calling
code only needs to keep the old file identifier returned by
gsd_open_read. The routine gsd_inquire_array is not implemented,
gsd_inq_size must be used instead.

The next inner layer is the external C binding. The C binding is similar
to the Fortran binding in that there is a one-to-one relationship
between routines. The C binding does not use inherited status, but
returns a status as the function value. Also, given scalar arguments are
passed by value, not by reference. An open GSD file is identfied by no
less than four pointers, all of which must be kept by the calling code.
The C binding consists of gsdOpenRead.c, gsdClose.c, gsdFind.c,
gsdItem.c, gsdInqSize.c, gsdGet0x.c, gsdGet1x.c.

The next inner layer are the gsd1_ routines. There are three routines
used by gsdOpenRead to open the file and read its contents into memory.
The fourth routine gsd1_getval returns information about and values of
items to the caller. It retrieves this information from the memory copy
of the file as created by gsdOpenRead.

The innermost layer are the gsd2_ routines. There are the gsd2_nativx
routines, which are used by the gsd1_ routines. They convert VAX binary
file contents to equivalent numbers in the format of the local machine.
They also convert VAX/GSD bad values to local/PRIMDAT bad values. Then
there is the gsd2_copya routine, which is used by gsd1_getval to convert
from the data type as copied from the file to the data type as required
by the calling routine.



Features of the library
-----------------------

The library provides only read access.

Only VAX-binary GSD files can be read.

Bad values in the file are converted to PRIMDAT bad values, which differ
from the traditional VAX/GSD bad values. (This conversion is in memory
only, the file itself is unchanged.)

Type conversion is possible only between numeric types (including
logical). Numeric to character or character to numeric conversion is not
provided by the library.

The recommended binding is the C binding.

The Fortran binding is incomplete and existing code calling GSD may need
modifications. See gsd_print.f.

   Only a rudimentary include file GSDPARS is provided. It also requires
   prior inclusion of PRM_PAR.

   Error status values have changed. Zero is good status, non-zero is
   bad status, but no particular status value can be expected.

   gsd_inquire_array is not implemented. Instead gsd_inq_size must be
   used, although it was previously labelled "obsolete".
