Data Interface

Data access in GIPSY is done through a set of routines collectively known under the name ``GDS'' (GIPSY Data System).

Image and Descriptor

The standard structure in which GIPSY stores data is called a set. A set consists of one or two files: the descriptor file and the image file. The programmer does not need to access these files directly; this is done for him by the GDS routines.

The descriptor can contain information which describes the associated image, but it is also suitable for other information. In fact a descriptor can be used in its own right, without an accompanying image. The descriptor describes the image file with FITS-like keywords.

The term image is used in a very general sense: it can be any equally spaced 0...N-dimensional structure of floating point numbers: spectra, images, Westerbork cubes, etc.

Coordinates and levels

In GIPSY there are kinds of coordinates:
  1. file coordinates, which are directly related to the position in the file;
  2. grid coordinates, related to the position with respect to the symbolic axes;
  3. physical or astronomical coordinates.
Users deal with physical and grid coordinates; programmers eventually work with grid coordinates, after any user input has been transformed into the proper format.

Coordinate words

In GDS file coordinates are often represented as coordinate words. A coordinate word is an integer value into which the position of any subset (pixels, lines, planes etc.) can be coded. Programmers do not normally manipulate coordinate words; this is done by a set of routines with that purpose. To use coordinate words one need not know how they are encoded. The exception is the value zero, which can be used to designate the whole set.

Levels

The term level is used to designate the coordinates of a subset. It is often used in the context of descriptor items.

Descriptor items

The descriptor file (or ``header'') is a hierarchical structure which allows the user to store information at every possible subset level by specifying the coordinates of that subset. All subsets, from the whole set down to the pixel level, can have descriptors of their own.

Basis GDS

In its most elementary form, a descriptor item is a string of bytes, identified by its level and a 20-character name. The basic GDS routines allow to read and write any number of bytes at any position. When writing, the length of the descriptor item can increase.

To retrieve a descriptor item, given its name and level, the GDS reading routines start looking at the specified level and if it is not found there, higher levels are tried. This process continues until the item is found or proven not to be present. This scheme allows for instance a descriptor item with a value for the whole set to be placed at top level, while items with the same name at lower levels can be used for exceptions from the general case. This `searching up'-behaviour can be suppressed by calling the routine GDST_ABSLEVEL. The GDS writing routines write at the specified level.

Application programmers do not normally use the basic GDS routines, but use a set of higher level routines instead which in turn call the basic routines.

FITS-type descriptor items

FITS-type descriptor items are the most commonly used in GIPSY. In form and function they follow the FITS standard. Examples are `DATAMIN' and `DATAMAX'. These hold the information about the minimum and maximum value in a particular subset. FITS descriptors are read and written using the routines in GDSD_Rxxx and GDSD_Wxxx. There exists a list of the most commonly used descriptor items.

Image data

Image data is read and written using the routines GDSI_READ and GDSI_WRITE. If the amount of data to be transferred is larger than the supplied buffer, a sequence of calls is necessary. Such a sequence is controlled by the transfer-id argument. See example. An incomplete transfer can be cancelled by calling GDSI_CANCEL.

Error handling

Every GDS routine has an integer error argument, which often is optional. If the argument is specified, it should be set to zero before the routine is called. Upon return the argument can then be checked. A negative value means that an error has occurred. Such a value can be translated into a message using the function GDS_ERRSTR. Some GDS routines use the error argument also for returning other information, such as the subset where an item is found. Such values are always positive.

When a GDS routine is called with a negative error argument, e.g. as the result of a previous call without clearing the argument, a fatal error will be generated.

When the error argument is omitted, any error will generate a fatal error immediately.

Programming GIPSY