A Technical Overview

A GSD file has a fairly simple layout. It consists of a ‘prolog’ followed by ‘data’. The prolog describes the data and can be used for retrieving it. The prolog consists of a single “file descriptor” and “item descriptors”, one for each data item. The item descriptor locates the required item in the byte stream. More information on the file structure can be found in [1].

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 contains 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[6]. 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.