IDL BINDINGS FOR GETDATA
========================

The IDL bindings for GetData provide bindings to the GetData library for the
Interactive Data Language developed by Research Systems, Incorporated.  They
provide a dynamically loaded module (DLM) `idl_getdata.so', described by
`idl_getdata.dlm', written in C, which will be installed in IDL's DLM search
path.  The bindings should work with any version of IDL from version 5.5
onwards, but are not compatible with earlier versions.

Using DLMs
----------

If the DLM is installed in the correct place and found by the interpreter, no
work should be needed to have the GetData functions available in the
interpreter.  To check if the GetData bindings have been found, execute:

  IDL> HELP, /DLM
 
If the GetData IDL bindings have been found, you should see among the output
something similar to:

  *** GETDATA - IDL GetData bindings (not loaded)
      Version: 0.10.0, Build Date: Tue Jan 25 00:00:00 PST 2017, Source: The GetData Project <getdata-devel@lists.sourceforge.net>
      Path: /usr/local/rsi/idl/bin/bin.linux.x86/idl_getdata.so

The DLM will be automatically loaded by the interpreter the first time a IDL
GetData function or procedure is referenced.  If no GETDATA entry is present,
in the list returned by the above command, check that these bindings have been
installed in the correct place.  The current DLM search path can be printed
with:

  IDL> PRINT, !DLM_PATH

If you find that the install process has installed idl_getdata.so in the wrong
place you can either:

* change the installed location by passing --with-idl-dlm-dir=PATH to GetData's
  ./configure script, and rebuild GetData, or

* change IDL's DLM search path by setting or modifying the environmental
  variable IDL_DLM_PATH before starting the IDL interpreter.  See Appendix D
  of the IDL Reference Guide for further details.

This situation should be unlikely, since the DLM install directory is determined
by ./configure by running the IDL interpreter to read the value of !DLM_PATH
explicitly.

NB: Third-party DLMs, such as these bindings, cannot be used in timed demo mode.
To use the IDL GetData bindings, a fully licensed version of IDL is required.
An unlicensed version of IDL will never find these bindings.


IDL GetData Preliminaries
-------------------------

Because the GetData library relies on a large number of symbolic constants, a
convenience function, GETDATA_CONSTANTS() is provided.  This function will
create a structure of constants, with member names identical to the GetData
C API's symbolic constants, but without the initial GD_ (eg. E_OK, INT8, &c.).
This is a structure of type `GD_CONSTANTS', which is defined in the bindings.
The typical use of this function is to define a new system variable, called
`!GD' which can then be used to reference these constants, when necessary.
This can be done using the following command:

  IDL> DEFSYSV, "!GD", GETDATA_CONSTANTS()

although this isn't strictly necessary, since constants could be fetched from
GETDATA_CONSTANTS() as necessary, if desired.  Nevertheless, for simplicity,
the remainder of this documentation refers to the system variable !GD as
defined above, whenever it needs to refer to a GetData constant.

Instead of using a DIRFILE pointer, an integer dirfile unit number is used to
refer to an open dirfile object.  Space is available in the DLM for only 1023
dirfile units.  If an application attempts to open more than 1023 dirfiles
simultaneously, the DLM will emit an error message and immediately return to the
interpreter.  Passing an invalid dirfile unit number to a procedure which
requires one as input (other than GD_CLOSE and GD_DISCARD, which will simply
ignore it) will result in the call failing with error code !GD.E_BAD_DIRFILE.

IDL supports all GetData data types with the exception of INT8.  Attempting to
return data as INT8 will result in an error.

Except for the functions GETDATA_CONSTANTS, GD_ERROR, GD_ERROR_COUNT,
GD_ERROR_STRING, and GD_INVALID_DIRFILE, all IDL GetData functions and
procedures may take two optional keyword parameters which deal with error
reporting:

  ERROR:   a variable into which the dirfile error number resulting from this
           call will be stored.  It will be the !GD.E_* error code corresponding
           to the C API error code.  On success this will be !GD.E_OK (= 0).  If
           this parameter is not specified, the dirfile error can still be
           retrieved by calling GD_ERROR() after this call.
  ESTRING: a variable in which the string representation of the error resulting
           from this call will be stored.  If this parameter is not specified,
           the the dirfile error string can still be retrieved by calling
           GD_ERROR_STRING() after the call.

For brevity, these keyword parameters are omitted from the subroutine prototypes
given below.

The GD_ENTRY Structure
----------------------

The GD_ENTRY structure is used in place of the C API's gd_entry_t data type.  It
is essentially equivalent and is defined as:

** Structure GD_ENTRY, 30 tags, length=568, data length=546:
  FIELD        STRING
  FIELD_TYPE   INT
  FLAGS        UINT
  FRAGMENT     INT
  IN_FIELDS    STRING     Array[3]
  A            DOUBLE     Array[6]
  CA           DCOMPLEX   Array[6]
  ARRAY_LEN    INT
  B            DOUBLE     Array[3]
  CB           DCOMPLEX   Array[3]
  BITNUM       INT
  COUNT_VAL    INT
  DATA_TYPE    INT
  DIVIDEND     DOUBLE
  CDIVIDEND    DCOMPLEX
  M            DOUBLE     Array[3]
  CM           DCOMPLEX   Array[3]
  N_FIELDS     INT
  NUMBITS      INT
  PERIOD       INT
  POLY_ORD     INT
  SCALAR       STRING     Array[6]
  SCALAR_IND   INT        Array[6]
  SHIFT        LONG
  SPF          UINT
  TABLE        STRING
  UTHRESHOLD   ULONG
  ITHRESHOLD   LONG
  RTHRESHOLD   DOUBLE
  WINDOP       INT

The DATA_TYPE member is used for both RAW and CONST fields.  (The gd_entry_t
object has a 'const_type' member for the CONST fields instead.)  For details on
how to use this structure, see the gd_entry(3) manual page.


IDL GetData Subroutines
-----------------------

The following subroutines are available in the IDL GetData bindings.
In general, they are named equivalently to their counterparts in the C API,
and differences in behaviour from the C API functionality is noted below.
Keyword parameters are always optional, unless noted below.

FUNCTION GETDATA_CONSTANTS()

  This function takes no inputs or keyword parameters, and returns a
  GD_CONSTANTS structure defining various useful GetData library constants.  The
  use of this function is discussed further above.

PROCEDURE GD_ADD, dirfile_unit, entry, PARENT=parent

  This procedure adds the field entry given by 'entry' to the dirfile.  The
  'entry' input should be a GD_ENTRY structure.  If the keyword parameter
  PARENT is given, the field will be added as a metafield under the given parent
  field, otherwise the field will be added to the fragment index indicated in
  the 'entry' structure.  See gd_add(3) and gd_madd(3).

PROCEDURE GD_ADD_ALIAS, dirfile_unit, field_code, target, FRAGMENT=fragment,
  PARENT=parent

  This procedure adds an alias called 'field_code' pointing to 'target' to
  the fragment indicated by 'fragment'.  See gd_add_alias(3).

PROCEDURE GD_ADD_BIT, dirfile_unit, field_name, in_field, BITNUM=bitnum,
  FRAGMENT=fragment, NUMBITS=numbits, PARENT=parent

  This procedure adds a BIT field with the name 'field_name' to the dirfile.
  The input vector field is given by 'in_field'.  If not given, bitnum
  defaults to zero and numbits to one.  If PARENT is given, this field is
  added as a metafield under the given parent field.  Otherwise, the field is
  added to the fragment indexed by FRAGMENT, or the primary format file if
  FRAGMENT is not given either.  See gd_add_bit(3) and gd_madd_bit(3).

PROCEDURE GD_ADD_CARRAY, dirfile_unit, field_name, FRAGMENT=fragment,
  LENGTH=length, PARENT=parent, TYPE=type, VALUE=value

  This procedure adds a CARRAY field with the name 'field_name' to the dirfile.
  The storage type of the field is given by the TYPE keyword, which defaults to
  !GD.FLOAT64.  If given, the initial value of the field is given by the VALUE
  keyword, in this case LENGTH is ignored, if also given.  if VALUE is not
  given, LENGTH must be specified, and the field will be initialised to all
  zeros.  If PARENT is given, this field is added as a metafield under the
  given parent field.  Otherwise, the field is added to the fragment indexed by
  FRAGMENT, or the primary format file if FRAGMENT is not given either.  See
  gd_add_carray(3) and gd_madd_carray(3).

PROCEDURE GD_ADD_CONST, dirfile_unit, field_name, FRAGMENT=fragment,
  PARENT=parent, TYPE=type, VALUE=value

  This procedure adds a CONST field with the name 'field_name' to the dirfile.
  The storage type of the field is given by the TYPE keyword, which defaults to
  !GD.FLOAT64.  The initial value of the field is given by the VALUE keyword,
  which defaults to zero.  If PARENT is given, this field is added as a
  metafield under the given parent field.  Otherwise, the field is added to the
  fragment indexed by FRAGMENT, or the primary format file if FRAGMENT is not
  given either.  See gd_add_const(3) and gd_madd_const(3).

PROCEDURE GD_ADD_DIVIDE, dirfile_unit, field_name, in_field1, in_field2,
  FRAGMENT=fragment, PARENT=parent

  This procedure adds a DIVIDE field with the name 'field_name' to the dirfile. 
  The input vector fields are given by 'in_field1' and 'in_field2'.  If PARENT
  is given, this field is added as a metafield under the given parent field.
  Otherwise, the field is added to the fragment indexed by FRAGMENT, or the
  primary format file if FRAGMENT is not given either.  See gd_add_divide(3)
  and gd_madd_divide(3).

PROCEDURE GD_ADD_LINCOM, dirfile_unit, field_name, in_field1, m1, b1,
  [in_field2, m2, b2, [in_field3, m3, b3,]] FRAGMENT=fragment, PARENT=parent

  This procedure adds a LINCOM field with the name 'field_name' to the dirfile.
  The number of fields in the LINCOM is determined by the number of inputs
  passed to the function.  The scale factors and offset terms may be real or
  complex valued.  If PARENT is given, this field is added as a metafield under
  the given parent field.  Otherwise, the field is added to the fragment indexed
  by FRAGMENT, or the primary format file if FRAGMENT is not given either.  See
  gd_add_lincom(3), gd_add_clincom(3), gd_madd_lincom(3), and
  gd_madd_clincom(3). 

PROCEDURE GD_ADD_LINTERP, dirfile_unit, field_name, in_field, table,
  FRAGMENT=fragment, PARENT=parent

  This procedure adds a LINTERP field with the name 'field_name' to the dirfile.
  The input vector field is given by 'in_field', and pathname of the look up
  table is 'table'.  If PARENT is given, this field is added as a metafield
  under the given parent field.  Otherwise, the field is added to the fragment
  indexed by FRAGMENT, or the primary format file if FRAGMENT is not given
  either.  See gd_add_linterp(3) and gd_madd_linterp(3).

PROCEDURE GD_ADD_MPLEX, dirfile_unit, field_name, in_field, count_field,
  value, FRAGMENT=fragment, MAX=max, PARENT=parent

  This procedure adds a MPLEX field with the name 'field_name' to the dirfile.
  The input vector is 'in_field', the multiplex index vector is 'count_field',
  the value of the multiplex index is 'value' and the maximum value is 'max',
  if specified.  If PARENT is given, this field is added as a metafield under
  the given parent field.  Otherwise, the field is added to the fragment indexed
  by FRAGMENT, or the primary format file if FRAGMENT is not given either.  See
  gd_add_mplex(3) and gd_madd_mplex(3).

PROCEDURE GD_ADD_MULTIPLY, dirfile_unit, field_name, in_field1, in_field2,
  FRAGMENT=fragment, PARENT=parent

  This procedure adds a MULTIPLY field with the name 'field_name' to the
  dirfile.  The input vector fields are given by 'in_field1' and 'in_field2'.
  If PARENT is given, this field is added as a metafield under the given parent
  field.  Otherwise, the field is added to the fragment indexed by FRAGMENT, or
  the primary format file if FRAGMENT is not given either.  See
  gd_add_multiply(3) and gd_madd_multiply(3).

PROCEDURE GD_ADD_PHASE, dirfile_unit, field_name, in_field, shift,
  FRAGMENT=fragment, PARENT=parent

  This procedure adds a PHASE field with the name 'field_name' to the dirfile.
  The input vector field is given by 'in_field' and the shift by 'shift'.  If
  PARENT is given, this field is added as a metafield under the given parent
  field.  Otherwise, the field is added to the fragment indexed by FRAGMENT, or
  the primary format file if FRAGMENT is not given either.  See gd_add_phase(3)
  and gd_madd_phase(3).

PROCEDURE GD_ADD_POLYNOM, dirfile_unit, field_name, in_field, a0, [a1, [a2,
  [a3, [a4, [a5,]]]]] FRAGMENT=fragment, PARENT=parent

  This procedure adds a POLYNOM field with the name 'field_name' to the dirfile.
  The input vector field is given by 'in_field' and the shift by the remaining
  inputs.  The order of the polynomial will be automatically determined by the
  number of co-efficients given.  If only a0 is given, it should be an array
  containing the co-efficients, otherwise each a<i> should be one co-efficient.
  If PARENT is given, this field is added as a metafield under the given parent
  field.  Otherwise, the field is added to the fragment indexed by FRAGMENT, or
  the primary format file if FRAGMENT is not given either.  See
  gd_add_polynom(3) and gd_madd_polynom(3).

PROCEDURE GD_ADD_RAW, dirfile_unit, field_name data_type, FRAGMENT=fragment,
  SPF=spf

  This procedure adds a RAW field with the name 'field_name' to the dirfile.
  The data type specified by 'data_type' should be one of the data type
  constants: !GD.UINT8, !GD.INT8, &c.  The number of samples per frame of the
  raw data is given by the SPF keyword, which defaults to one, if not given.
  The field will be added to the fragment indexed by FRAGMENT, if given, or else
  to the primary format file.  See gd_add_raw(3).

PROCEDURE GD_ADD_RECIP, dirfile_unit, field_name, in_field, DIVIDEND=dividend,
  FRAGMENT=fragment, PARENT=parent

  This procedure adds a RECIP field with the name 'field_name' to the dirfile.
  The input vector field is given by 'in_field'.  If not given, dividend
  defaults to one.  If PARENT is given, this field is added as a metafield under
  the given parent field.  Otherwise, the field is added to the fragment
  indexed by FRAGMENT, or the primary format file if FRAGMENT is not given
  either.  See gd_add_recip(3), gd_add_crecip(3), gd_madd_recip(3),
  gd_madd_crecip(3).

PROCEDURE GD_ADD_SBIT, dirfile_unit, field_name, in_field, BITNUM=bitnum,
  FRAGMENT=fragment, NUMBITS=numbits, PARENT=parent

  This procedure adds a SBIT field with the name 'field_name' to the dirfile.
  The input vector field is given by 'in_field'.  If not given, bitnum
  defaults to zero and numbits to one.  If PARENT is given, this field is
  added as a metafield under the given parent field.  Otherwise, the field is
  added to the fragment indexed by FRAGMENT, or the primary format file if
  FRAGMENT is not given either.  See gd_add_sbit(3) and gd_madd_sbit(3).

PROCEDURE GD_ADD_SPEC, dirfile_unit, line, FRAGMENT=fragment, PARENT=parent

  This procedure adds a field described by the field specification line 'line'
  to the dirfile.  If PARENT is given, this field is added as a metafield under
  the given parent field.  Otherwise, the field is added to the fragment indexed
  by FRAGMENT, or the primary format file if FRAGMENT is not given either.  See
  gd_add_spec(3) and gd_madd_spec(3).

PROCEDURE GD_ADD_STRING, dirfile_unit, field_name, FRAGMENT=fragment,
  PARENT=parent, VALUE=value

  This procedure adds a STRING field with the name 'field_name' to the dirfile.
  The initial value of the field is given by the VALUE keyword, which defaults
  to the empty string.  If PARENT is given, this field is added as a metafield
  under the given parent field.  Otherwise, the field is added to the fragment
  indexed by FRAGMENT, or the primary format file if FRAGMENT is not given
  either.  See gd_add_string(3) and gd_madd_string(3).

PROCEDURE GD_ADD_WINDOW, dirfile_unit, field_name, in_field, check_field,
  threshold, /CLR, /EQ, /GE, /GT, /LE, /LT, /NE, /SET, FRAGMENT=fragment,
  PARENT=parent

  This procedure adds a WINDOW field with the name 'field_name' to the dirfile.
  The input vector field is given by 'in_field' and the check field is given by
  'check_field.  The window operation is specified by one of the optional
  parameters, CLR, EQ, GE, &c.  If PARENT is given, this field is added as a
  metafield under the given parent field.  Otherwise, the field is added to the
  fragment indexed by FRAGMENT, or the primary format file if FRAGMENT is not
  given either.  See gd_add_window(3), and gd_madd_window(3).

FUNCTION GD_ALIASES(dirfile_unit, field_code)

  This function returns a list of aliases of 'field_code' (including field_code)
  itself.  See gd_aliases(3).

FUNCTION GD_ALIAS_TARGET(dirfile_unit, field_code)

  This procedure returns the target pointed to by the alias 'field_code'.  See
  gd_alias_target(3).

PROCEDURE GD_ALTER_AFFIXES(dirfile_unit, FRAGMENT=fragment, PREFIX=prefix,
  SUFFIX=suffix)

  This procedure modifies the prefix and/or suffix of the fragment index
  specified by FRAGMENT.  Zero is assumed if FRAGMENT is not specified.  See
  gd_alter_affixes(3).

PROCEDURE GD_ALTER_BIT, dirfile_unit, field_code, BITNUM=bitnum,
  IN_FIELD=in_field, NUMBITS=numbits

  This procedure modifies the metadata of the BIT field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  See gd_alter_bit(3).

PROCEDURE GD_ALTER_CARRAY, dirfile_unit, field_code, TYPE=type, LENGTH=length

  This procedure modifies the metadata of the field specified by 'field_code',
  updating the storage data type and array length if specified as keyword
  parameters.  If given, TYPE should be one of the data type constants:
  !GD.UINT8, !GD.INT8, &c.  See gd_alter_carray(3).

PROCEDURE GD_ALTER_CONST, dirfile_unit, field_code, TYPE=type

  This procedure modifies the metadata of the field specified by 'field_code',
  updating the storage data type if specified as a keyword parameter.  If given,
  TYPE should be one of the data type constants: !GD.UINT8, !GD.INT8, &c.  See
  gd_alter_const(3).

PROCEDURE GD_ALTER_DIVIDE, dirfile_unit, field_code, IN_FIELD1=in_field1,
  IN_FIELD2=in_field2

  This procedure modifies the metadata of the DIVIDE field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  See gd_alter_divide(3).

PROCEDURE GD_ALTER_ENCODING, dirfile_unit, encoding, FRAGMENT=fragment,
  /RECODE

  This procedure modifies the encoding of part or all of the dirfile.  The
  new encoding is given be 'encoding' and should either be a string indicating
  the encoding type: 'BZIP2', 'GZIP', 'LZMA', 'SLIM', 'TEXT', 'NONE', or else
  a numeric encoding type: !GD.BZIP2_ENCODED, &c.  If FRAGMENT is given, only
  the fragment with that index is modified, otherwise all fragments are
  modified.  If RECODE is specified, the data files on disk will be updated for
  the new encoding.  See gd_alter_encoding(3).

PROCEDURE GD_ALTER_ENDIANNESS, dirfile_unit, /ARM_ENDIAN, /BIG_ENDIAN,
  FRAGMENT=fragment, /LITTLE_ENDIAN, /NOT_ARM_ENDIAN, /RECODE

  This procedure modifies the byte sex of part or all of the dirfile.  The
  new byte sex is the bitwise or of the two endianness KEYWORD flags, if given,
  as described in the gd_alter_endianness manual page.  If FRAGMENT is
  given, only the fragment with that index is modified, otherwise all fragments
  are modified.  If RECODE is specified, the data files on disk will be updated
  for the new byte sex.  See gd_alter_endianness(3).

PROCEDURE GD_ALTER_ENTRY, dirfile_unit, field_code, entry, /RECODE

  This procedure modifies the field specified by 'field_code' to conform to
  the field metadata given in the GD_ENTRY structure 'entry'.  If RECODE is
  specified, and the field is a RAW or LINTERP entry, the data on disk will
  be updated to reflect changes to the field metadata.  See
  gd_alter_entry(3).

PROCEDURE GD_ALTER_FRAMEOFFSET, dirfile_unit, frameoffset,
  FRAGMENT=fragment, /RECODE

  This procedure modifies the frame offset of part or all of the dirfile.  The
  new frame offset is given by 'frameoffset'.  If FRAGMENT is given, only the
  fragment with that index is modified, otherwise all fragments are modified.
  If RECODE is specified, the data files on disk will be updated for the new
  frame offset.  See gd_alter_frameoffset(3).

PROCEDURE GD_ALTER_LINCOM, dirfile_unit, field_code, B=b,
  IN_FIELDS=in_fields, M=m, N_FIELDS=n_fields

  This procedure modifies the metadata of the LINCOM field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  If specified, B, IN_FIELDS, M must be arrays of length n_fields
  (which may be simultaneously updated).  The numeric parameters may be either
  real or complex valued.  If N_FIELDS specifies more fields than the field
  currently has, but B, IN_FIELDS, or M are not specified, the new values will
  contain uninitialised data.  See gd_alter_lincom(3) and gd_alter_clincom(3).

PROCEDURE GD_ALTER_LINTERP, dirfile_unit, field_code, IN_FIELD=in_field,
  /RENAME_TABLE, TABLE=table

  This procedure modifies the metadata of the LINTERP field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  If both TABLE and RENAME_TABLE are specified, the name of the
  file containing the look up table will be renamed to reflect changes to the
  field metadata.  See gd_alter_linterp(3).

PROCEDURE GD_ALTER_MPLEX, dirfile_unit, field_code, COUNT_FIELD=count_field,
  PERIOD=period, COUNT_VAL=count_val, IN_FIELD=in_field

  This procedure modifies the metadata of the MPLEX field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  See gd_alter_mplex(3).

PROCEDURE GD_ALTER_MULTIPLY, dirfile_unit, field_code, IN_FIELD1=in_field1,
  IN_FIELD2=in_field2

  This procedure modifies the metadata of the MULTIPLY field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  See gd_alter_multiply(3).

PROCEDURE GD_ALTER_PHASE, dirfile_unit, field_code, IN_FIELD=in_field,
  SHIFT=shift

  This procedure modifies the metadata of the PHASE field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  See gd_alter_phase(3).

PROCEDURE GD_ALTER_POLYNOM, dirfile_unit, field_code, A=a,
  IN_FIELD=in_field, POLY_ORD=poly_ord

  This procedure modifies the metadata of the POLYNOM field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  If specified, A must be an array of length poly_ord + 1
  (which may be simultaneously updated).  This array may be either real or
  complex valued.  If POLY_ORD specifies a higher order than the field
  currently has, but A is not specified, the new co-efficients will contain
  uninitialised data.  This procedure may also be called GD_ALTER_CPOLYNOM
  without change in functionality.  See gd_alter_polynom(3) and
  gd_alter_cpolynom(3).

PROCEDURE GD_ALTER_RAW, dirfile_unit, field_code, /RECODE, SPF=spf,
  TYPE=type

  This procedure modifies the metadata of the RAW field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  If given, TYPE should be one of the data type constants:
  !GD.UINT8, !GD.INT8, &c.   If RECODE is specified, the file on disk backing
  this RAW file will be update to reflect changes in the field metadata.
  See gd_alter_raw(3).

PROCEDURE GD_ALTER_RECIP, dirfile_unit, field_code, DIVIDEND=dividend,
  IN_FIELD=in_field

  This procedure modifies the metadata of the RECIP field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  See gd_alter_recip(3) and gd_alter_crecip(3).

PROCEDURE GD_ALTER_SBIT, dirfile_unit, field_code, BITNUM=bitnum,
  IN_FIELD=in_field, NUMBITS=numbits

  This procedure modifies the metadata of the SBIT field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  See gd_alter_sbit(3).

PROCEDURE GD_ALTER_SPEC, dirfile_unit, line, PARENT=parent, /RECODE

  This procedure modifies the metadata of the field specified by the field
  specification line 'line' to conform to the specification.  If /RECODE is
  given, data on disk is update, if applicable, to correspond with changes made
  to the field metadata.  If PARENT is given, the field is assumed to be a
  metafield under the given parent.  See gd_alter_spec(3) and gd_malter_spec(3).

PROCEDURE GD_ALTER_WINDOW, dirfile_unit, field_code, CHECK_FIELD=check_field,
  /CLR, /EQ, /GE, /GT, IN_FIELD=in_field, /LE, /LT, /NE, /SET,
  THRESHOLD=threshold

  This procedure modifies the metadata of the WINDOW field specified by
  'field_code', updating only those field parameters specified as keyword
  parameters.  See gd_alter_window(3).

FUNCTION GD_BOF(dirfile_unit, field_code)

  This function returns the sample number of the position of the
  beginning-of-field marker for the specified field.  See gd_bof(3).

FUNCTION GD_CARRAY_LEN(dirfileunit, field_code)

  This function returns the length of the specified field.  See
  gd_carray_len(3).

PROCEDURE GD_CLOSE, dirfile_unit, /DISCARD

  This procedure closes the specified dirfile.  If DISCARD is not given, pending
  metadata changes are first flushed to disk.  In all cases, pending data writes
  are flushed to disk before close.  See gd_close(3) and
  gd_discard(3).

FUNCTION GD_CONSTANTS(dirfile_unit, PARENT=parent, TYPE=type)

  This function returns the value of all CONST fields in the dirfile, converting
  them to the return type specified by TYPE, which should be one of the data
  type constants: !GD.UINT8, !GD.UINT16, &c.  If TYPE is not specified, the
  values are returned as double precision data, even if they are stored as
  complex values.  If PARENT is given, the value of CONST metafields defined
  for the given parent field will be returned, otherwise all non-meta CONST
  fields will be returned.  See gd_constants(3) and gd_mconstants(3).

PROCEDURE GD_DELETE, dirfile_unit, field_code, /DEL_DATA, /DEREF, /FORCE, /META

  This procedure delete the field or alias specified by 'field_code' from the
  database.  The meanings of the keyword flags are discussed in the gd_delete(3)
  manual page (q.v.).

FUNCTION GD_DESYNC(dirfile_unit, /PATHCHECK, /REOPEN)

  This function returns non-zero if the loaded dirfile has become desynchronised
  from the metadata on disk (due to a third party modifying the dirfile on
  disk).  If /PATHCHECK is specified, the metadata on disk will be probed via
  the full canonicalised pathnames to the fragment files, otherwise the
  dirfile's cached directory descriptors will be used.  If /REOPEN is given,
  the dirfile will be rescanned and updated if a change is discovered.  See
  gd_desync(3).

FUNCTION GD_DIRFILENAME(dirfile_unit)

  This function returns the name of the dirfile specified by 'dirfile_unit'.
  See dirfilename(3).

FUNCTION GD_DIRFILE_STANDARDS(dirfile_unit, [version,] /LATEST, /EARLIEST)

  This function returns the current Standards Version of the loaded dirfile,
  optionally setting it first.  If more than one of version, LATEST or
  EARLIEST are provided, results are undefined.  See gd_dirfile_standards(3).

FUNCTION GD_ENCODING(dirfile_unit, FRAGMENT=fragment)

  This function returns the encoding scheme of the fragment indexed by FRAGMENT,
  or of the primary format file, if FRAGMENT is omitted.  The return value will
  be one of the !GD.*_ENCODED constants.  See gd_encoding(3).

FUNCTION GD_ENCODING_SUPPORT(encoding)

  This function returns !GD.RDWR, !GD.RONLY, or -1 depending on the runtime
  support for the specified encoding.  See gd_encoding_support(3).

FUNCTION GD_ENDIANNESS(dirfile_unit, FRAGMENT=fragment)

  This function returns the byte sex of the fragment indexed by FRAGMENT, or of
  the primary format file, if FRAGMENT is omitted.  The return value will be
  one of !GD.BIG_ENDIAN or !GD.LITTLE_ENDIAN bitwise or'd with one of
  !GD.ARM_ENDIAN or !GD.NOT_ARM_ENDIAN.  See gd_endianness(3).

FUNCTION GD_ENTRY(dirfile_unit, field_code)

  This function returns a GD_ENTRY structure containing the field metadata for
  the field specified by 'field_code'.  See gd_entry(3).

FUNCTION GD_ENTRY_TYPE(dirfile_unit, field_code)

  This function returns the field type of the field specified by 'field_code'.
  The returned value will be one of the !GD.*_ENTRY constants.  See
  gd_entry_type(3).

FUNCTION GD_EOF(dirfile_unit, field_code)

  This function returns the sample number of the position of the end-of-field
  marker for the specified field.  See gd_eof(3).

FUNCTION GD_ERROR(dirfile_unit)

  This function returns the error status of the last call to the GetData library
  on the specified dirfile.  The return value will be one of the !GD.E_* codes.
  This function does not take the normal ERROR and ESTRING keyword parameters.
  See gd_error(3).

FUNCTION GD_ERROR_COUNT(dirfile_unit)

  This function returns the number of errors encountered by the GetData library
  on the specified dirfile since this function was last called (or since the
  dirfile was opened, if this is the first call to this function).  See
  gd_error_count(3).

FUNCTION GD_ERROR_STRING(dirfile_unit)

  This function returns a human readable string describing the error status of
  the last call to the GetData library on the specified dirfile.  This function
  does not take the normal ERROR and ESTRING keyword parameters.  See
  gd_error_string(3).

FUNCTION GD_FIELD_LIST(dirfile_unit, /HIDDEN, /NOALIAS, PARENT=parent, /SCALARS,
    TYPE=type, /VECTORS)

  An alias for GD_ENTRY_LIST (q.v.) kept for backwards compatibility.

FUNCTION GD_FLAGS(dirfile_unit, PRETTY_PRINT=pretty_print, VERBOSE=verbose)

  This function modifies the operational flags of the dirfile.  If a keyword
  parameter is zero, the corresponding flag will be cleared; if a keyword
  parameter is one, the corresponding flag will be set; otherwise, the flag is
  unchanged.  The function returns the value of the flags register after
  modification.  See gd_flags(3).

PROCEDURE GD_FLUSH, dirfile_unit, FIELD_CODE=field_code, /NOCLOSE, /NOSYNC

  This procedure flushes pending data writes to disk.  If FIELD_CODE is given,
  only writes for the given field are flushed to disk.  Otherwise, all fields
  and metadata changes are flushed to disk.  In normal operation, first the
  raw data is flushed (synced) and then the raw data files are closed.
  Specifying /NOSYNC will skip the flushing; specifying /NOCLOSE will skip the
  closing.  Specifying both will result in an error (since the function is left
  with nothing to do.)  See gd_flush(3), gd_sync(3) and gd_raw_close(3).

FUNCTION GD_FRAGMENT_AFFIXES(dirfile_unit, FRAGMENT=fragment)

  This function returns a two element array of the field code prefix and suffix
  of the fragment specified by FRAGMENT.  Zero is assumed if FRAGMENT is not
  specified.  See gd_fragment_affixes(3).

FUNCTION GD_FRAGMENT_INDEX(dirfile_unit, field_code)

  This function returns the index of the format file fragment which defines the
  field specified by 'field_code'.  See gd_fragment_index(3).

FUNCTION GD_FRAGMENTNAME(dirfile_unit, fragment_index)

  This function returns the pathname of the format file fragment indexed by
  'fragment_index'.  See gd_fragmentname(3).

FUNCTION GD_FRAMENUM(dirfile_unit, field_code, value, FIELD_START=field_start,
  FIELD_END=field_end)

  This function performs a reverse look up on the field specified by
  'field_code'.  It returns the fractional frame number where the field has the
  value given by 'value'.  The search is performed between the frame limits
  FRAME_START and FRAME_END.  If FRAME_START is omitted, the beginning of the
  frame is used; if FRAME_END is omitted, the end of frame is used.  See
  gd_framenum(3) and gd_framenum_subset(3).

FUNCTION GD_FRAMEOFFSET(dirfile_unit, FRAGMENT=fragment_index)

  This function returns the frame offset of the fragment indexed by FRAGMENT, or
  of the primary format file, if FRAGMENT is omitted.  See gd_frameoffset(3).

FUNCTION GD_GETDATA(dirfile_unit, field_code, FIRST_FRAME=first_frame,
  FIRST_SAMPLE=first_sample, NUM_FRAMES=num_frames, NUM_SAMPLES=num_samples,
  TYPE=type)

  This function retrieves data from the field specified by 'field_code'.  It
  returns a list of data, of the type given by TYPE, which should be one of the
  data type constants: !GD.UINT8, !GD.UINT16, &c.  If TYPE is omitted, this
  function returns double precision data, even if originally complex valued.
  The first sample read is given by FIRST_FRAME and/or FIRST_SAMPLE.  If neither
  of these are given, reading occurs at the current position.  The number of
  samples requested is given by NUM_FRAMES and/or NUM_SAMPLES.  Fewer samples
  than requested may be returned, without causing an error, if the end of the
  field is encountered.  See getdata(3).

FUNCTION GD_GET_CARRAY(dirfile_unit, field_code, TYPE=type)

  This function returns the value of a CONST field, converting it to the return
  type specified by TYPE, which should be one of the data type constants:
  !GD.UINT8, !GD.UINT16, &c.  If TYPE is not specified, the value is returned as
  a double precision number, even if complex valued.  See gd_get_constant(3).

FUNCTION GD_GET_CONSTANT(dirfile_unit, field_code, LENGTH=length, START=start,
  TYPE=type)

  This function returns all or part of a CARRAY field, converting the data to
  the return type specified by TYPE, which should be one of the data type
  constants: !GD.UINT8, !GD.UINT16, &c.  If TYPE is not specified, !GD.FLOAT64
  is assumed.  The first element returned is given by the START keyword,
  which defaults to zero.  If LENGTH is not specified, all elements from START
  to the end of the field are returned, otherwise.  See gd_get_carray_slice(3).

FUNCTION GD_GET_STRING(dirfile_unit, field_code)

  This function returns the value of a STRING field specified by 'field_code'.
  See gd_get_string(3).

FUNCTION GD_HIDDEN(dirfile_unit, field_code)

  This function returns one if the field or alias specified by 'field_code' is
  hidden, or zero if it is not.  On error it returns -1.  See gd_hidden(3).

PROCEDURE GD_HIDE, dirfile_unit, field_code

  This procedure hides the field or alias specified by 'field_code'.  See
  gd_hide(3).

PROCEDURE GD_INCLUDE, dirfile_unit, fragment_name, /ARM_ENDIAN, /BIG_ENDIAN,
  /CREAT, ENCODING=encoding, /EXCL, /FORCE_ENCODING, /FORCE_ENDIANNESS,
  FRAGMENT=fragment, INDEX=index, /IGNORE_DUPS, /IGNORE_REFS, /LITTLE_ENDIAN,
  /NOT_ARM_ENDIAN, /PEDANTIC, /PERMISSIVE, PREFIX=prefix, SUFFIX=suffix, /TRUNC

  This procedure adds the format file fragment specified by 'fragment_name' to
  the format file indexed by FRAGMENT, or else the primary format file, if
  FRAGMENT is not given.  If specified, the fragment index of the newly added
  fragment is returned in INDEX.  If specified, ENCODING should either be a
  string indicating the encoding type: 'BZIP2', 'GZIP', 'LZMA', 'SLIM', 'TEXT',
  'NONE', or else a numeric encoding type: !GD.BZIP2_ENCODED, &c.  The meaning
  of the remaining keyword flags is discussed in the gd_include manual page.
  See gd_include(3) and gd_include_affix(3).
 
FUNCTION GD_INVALID_DIRFILE()

  This functions returns a dirfile unit number corresponding to a newly created
  invalid dirfile.  See gd_invalid_dirfile(3).

FUNCTION GD_MATCH_ENTRIES(dirfile_unit, /ALIASES, /CASELESS, /EXTENDED,
    FRAGMENT=fragment, /HIDDEN, /ICASE, /JAVASCRIPT, /NOALIAS, PARENT=parent,
    /PCRE, REGEX=regex, /SCALARS, TYPE=type, /UNICODE, /VECTORS)

  This function returns a list of entry names defined by the dirfile which
  satisfy the provided criteria.  Not all criteria may be used at the same time:
  if PARENT is given, then neither REGEX nor FRAGMENT may be supplied.

  The flags /CASELESS, /EXTENDED, /ICASE, /JAVASCRIPT, /PCRE, and /UNICODE affect
  the interpretation of REGEX.  If REGEX is not given, these flags are ignored.

  If REGEX is given, it is a regular expression which is matched against entry
  names.  If FRAGMENT is given, matching will be restricted to the entries
  defined in that fragment.  Otherwise, if PARENT is given, a list of metafields
  for the given parent will be returned otherwise top-level fields are considered.

  In both cases, if TYPE is given, which should be one of the !GD.*_ENTRY constants,
  only fields of the given type will be returned.  If /ALIASES, /SCALARS or /VECTORS
  is specified, the TYPE parameter is ignored if it is also given.  The list returned
  includes aliases, unless /NOALIAS is specified, but not hidden fields, unless
  /HIDDEN is specified.  See gd_entry_list(3) and gd_match_entries(3).

  This function may also be called as GD_ENTRY_LIST without change in parameters
  or behaviour.

PROCEDURE GD_METAFLUSH, dirfile_unit

  This procedure flushes pending metadata changes to the dirfile to disk.  See
  gd_metaflush(3).

PROCEDURE GD_MOVE, dirfile_unit, field_code, new_fragment, /DANGLE, /FORCE,
  /MOVE_DATA, /UPDATEDB

  This procedure moves the field or alias specified by 'field_code' to the 
  format file fragment indexed by 'new_fragment'.  See gd_move(3) for the
  meaning of the flags.

PROCEDURE GD_MPLEX_LOOKBACK dirfile_unit, [lookback,] /ALL

  This procedure sets the MPLEX lookback length to the value given, if supplied,
  or to the maximum value, if /ALL is given, or else to the default value if
  neither is provided.  See gd_mplex_lookback(3).

FUNCTION GD_NALIASES(dirfile_unit, field_code)

  This function returns the number of aliases of 'field_code' (including
  field_code itself).  See gd_naliases(3).

FUNCTION GD_NATIVE_TYPE(dirfile_unit, field_code)

  This function returns the native data type of the field given by 'field_code'.
  The return value will be one of the data type constants: !GD.UINT8, !GD.INT8,
  &c.  See gd_native_type(3).

FUNCTION GD_NENTRIES(dirfile_unit, /ALIAS, /HIDDEN, /NOALIAS, PARENT=parent,
    /SCALARS, TYPE=type, /VECTORS)

  This function returns the number of entries in the dirfile satisfying the
  given criteria.  If PARENT is given, the number of metafields for the given
  parent will be returned otherwise top-level fields are considered.  If TYPE is
  given, which should be one of the !GD.*_ENTRY constants, only fields of the
  given type will be counted.  If /ALIASES, /SCALARS or /VECTORS is specified,
  the TYPE parameter is ignored if it is also given.  The number returned
  includes aliases, unless /NOALIAS is specified, but not hidden fields, unless
  /HIDDEN is specified.  See gd_nentries(3).

FUNCTION GD_NFIELDS(dirfile_unit, /HIDDEN, /NOALIAS, PARENT=parent, /SCALARS,
    TYPE=type, /VECTORS)

  An alias for GD_NENTRIES (q.v.) kept for backwards compatibility.

FUNCTION GD_NFRAGMENTS(dirfile_unit)

  This function returns the number of format file fragments in the dirfile.
  See gd_nfragments(3).

FUNCTION GD_NFRAMES(dirfile_unit)

  This function returns the number of frames in the dirfile.  See
  gd_nframes(3).

FUNCTION GD_NVECTORS(dirfile_unit, PARENT=parent)

  This function returns the number of vector type fields defined by the dirfile.
  If PARENT is given, the number vector type metafields for the given parent
  will be returned.  Otherwise, the total number of vector fields in the
  database will be returned.  See gd_nvectors(3) and gd_nmvectors(3).

FUNCTION GD_OPEN(dirfilename, /ARM_ENDIAN, /BIG_ENDIAN, /CREAT,
  ENCODING=encoding, /EXCL, /FORCE_ENCODING, /FORCE_ENDIANNESS, /IGNORE_DUPS,
  /IGNORE_REFS, /LITTLE_ENDIAN, /NOT_ARM_ENDIAN, /PEDANTIC, /PERMISSIVE,
  /PRETTY_PRINT, /RDWR, /TRUNC, /TRUNCSUB, /VERBOSE)

  This function opens the dirfile specified by 'dirfilename', returning the
  dirfile unit number which can be subsequently used to refer to it.  If
  specified, ENCODING should either be a string indicating the encoding type:
  'BZIP2', 'GZIP', 'LZMA', 'SIE', 'SLIM', 'TEXT', 'ZZIP', 'ZZSLIM', 'NONE', or
  else a numeric encoding type: !GD.BZIP2_ENCODED, &c.  The meaning of the other
  keyword flags is explained in the gd_open(3) manual page.  A parser callback
  function cannot be used by the IDL GetData bindings.  See gd_open(3).

FUNCTION GD_PARENT_FRAGMENT(dirfile_unit, fragment_index)

  This function returns the index of the format file fragment which includes
  the fragment indexed by 'fragment_index'.  See gd_parent_fragment(3).

PROCEDURE GD_PROTECT, dirfile_unit, protection, FRAGMENT=fragment

  This function changes the (advisory) protection level of the fragment indexed
  by FRAGMENT to 'protection', which should be one of the !GD.PROTECT_* values.
  If FRAGMENT is not given, the protection level of all fragments is changed.  
  See gd_protect(3).

FUNCTION GD_PROTECTION(dirfile_unit, FRAGMENT=fragment)

  This function returns the (advisory) protection level for the format file
  fragment indexed by FRAGMENT, or for the primary format file, if FRAGMENT is
  omitted.  The returned value will be one of the !GD.PROTECT_* constants.  See
  gd_protection(3).

PROCEDURE GD_PUTDATA, dirfile_unit, field_code, data, FIRST_FRAME=first_frame,
  FIRST_SAMPLE=first_sample

  This procedure writes data in the numerical vector 'data' to the field
  specified by 'field_code'.  The keywords FIRST_FRAME and/or FIRST_SAMPLE
  indicate the first sample written.  If neither of these are specified, the
  data is written at the current position.  See putdata(3).

PROCEDURE GD_PUT_CARRAY, dirfile_unit, field_code, value, START=start

  This procedure stores the data in 'value' to the CARRAY field specified by
  'field_code'.  START indicates the first element of the field which is
  written.  Zero is assumed for START if not given.  See gd_put_carray_slice(3).

PROCEDURE GD_PUT_CONSTANT, dirfile_unit, field_code, value

  This procedure stores the number 'value' in the CONST field specified by
  'field_code'.  See gd_put_constant(3).

PROCEDURE GD_PUT_STRING, dirfile_unit, field_code, value

  This procedure stores the string 'value' in the STRING field specified by
  'field_code'.  See gd_put_string(3).

FUNCTION GD_RAW_FILENAME(dirfile_unit, field_code)

  This function returns the pathname of the data file backing the RAW field
  specified by 'field_code'.  See gd_raw_filename(3).

FUNCTION GD_REFERENCE(dirfile_unit, [new_reference])

  This function returns the name of the RAW field used as the reference field
  for the dirfile, after optionally changing it to new_reference.  If the
  dirfile contains no reference field, the empty string is returned.  See
  gd_reference(3).

PROCEDURE GD_RENAME, dirfile_unit, field_code, new_name, /DANGLE, /FORCE,
  /MOVE_DATA, /UPDATEDB

  This function renames the field specified by 'field_code' to 'new_name'.  See
  gd_rename(3) for the meaning of the flags.

FUNCTION GD_SEEK(dirfile_unit, field_code, FRAME_NUM=frame_num,
  SAMPLE_NUM=sample_num, WHENCE=whence, /WRITE)

  This function sets the current I/O position of the field specified by
  'field_code' to the position given by FRAME_NUM and SAMPLE_NUM (which both
  default to zero).  WHENCE should be one of the !GD.SEEK_* symbols.  If the
  next operation on the field is a write (via GD_PUTDATA), the /WRITE flag
  should also be specified.  See gd_seek(3).

FUNCTION GD_SPF(dirfile_unit, field_code)

  This function returns the number of samples per frame of the field specified
  by 'field_code'.  See gd_spf(3).

FUNCTION GD_STRINGS(dirfile_unit, PARENT=parent, TYPE=type)

  This function returns the value of all STRING fields in the dirfile.  If
  PARENT is given, the value of STRING metafields defined for the given parent
  field will be returned, otherwise all non-meta STRING fields will be returned.
  See gd_strings(3) and gd_mstrings(3).

FUNCTION GD_STRTOK(dirfile_unit, STRING=string)

  If STRING is given, this function returns the first token of the string.
  Otherwise, it returns the next token of a string provided to a previous call.
  See gd_strtok(3).

FUNCTION GD_TELL(dirfile_unit, field_code)
  
  This function returns the current I/O position of the specified field.  See
  gd_tell(3).

PROCEDURE GD_UNHIDE, dirfile_unit, field_code

  This procedure unhides the field or alias specified by 'field_code'.  See
  gd_unhide(3).

PROCEDURE GD_UNINCLUDE, dirfile_unit, fragment_index, /DELETE

  This function removes the format file fragment indexed by 'fragment_index'.
  If DELETE is specified, the fragment is also deleted from disk.  See
  gd_uninclude(3).

FUNCTION GD_VALIDATE(dirfile_unit, field_code)

  This function checks whether 'field_code' is valid for reading and writing.
  If it is this function returns zero.  Otherwise it returns non-zero.  See
  gd_validate(3).

PROCEDURE GD_VERBOSE_PREFIX, dirfile_unit, PREFIX=prefix)

  This procedure sets the dirfile verbose prefix to PREFIX, if given, or else
  removes it.  See gd_verbose_prefix(3).

FUNCTION GD_VECTOR_LIST(dirfile_unit, PARENT=parent)

  This function returns a list of vector type fields defined by the dirfile.  If
  PARENT is given, a list of vector metafields for the given parent will be
  returned.  Otherwise all non-meta vector fields will be returned.  See
  gd_vector_list(3) and gd_mvector_list(3).