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:
- file coordinates, which are directly related to the position
in the file;
- grid coordinates, related to the position with respect to
the symbolic axes;
- 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.
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.
