NAME

       gd_add, gd_madd — add a field to a dirfile

SYNOPSIS

       #include <getdata.h>

       int gd_add(DIRFILE *dirfile, const gd_entry_t *entry);

       int gd_madd(DIRFILE *dirfile, const gd_entry_t *entry, const char *parent);

DESCRIPTION

       The  gd_add()  function  adds  the  field  described  by entry to the dirfile specified by
       dirfile.  The gd_madd() function behaves similarly, but adds  the  field  as  a  metafield
       under the field indicated by the field code parent.

       The  form  of  entry  is  described  in  detail on the gd_entry(3) man page.  All relevant
       members of entry for the field type specified must  be  properly  initialised.   If  entry
       specifies  a  CONST  or  CARRAY  field,  the  field's  data will be set to zero.  If entry
       specifies a STRING field, the field data will be set to the empty string.

       When adding a metafield, the entry->field member should contain just the metafield's name,
       not  the fully formed <parent-field>/<meta-field> field code.  Also, gd_madd() ignores the
       value of entry->fragment_index, and instead adds the new meta field  to  the  same  format
       specification fragment in which the parent field is defined.

       Fields added with this interface may contain either literal parameters or parameters based
       on scalar fields.  If an element of the entry->scalar  array  defined  for  the  specified
       field  type  is  non-NULL,  this  element  will  be used as the scalar field code, and the
       corresponding numerical member will be ignored, and need not be initialised.   Conversely,
       if  numerical  parameters are intended, the corresponding entry->scalar elements should be
       set to NULL.  If using an element of a CARRAY field, entry->scalar_ind should also be set.

RETURN VALUE

       On success, gd_add() and gd_madd() return zero.   On error, -1 is returned and the dirfile
       error is set to a non-zero error value.  Possible error values are:

       GD_E_ACCMODE
               The specified dirfile was opened read-only.

       GD_E_ALLOC
               The library was unable to allocate memory.

       GD_E_BAD_CODE
               The field name provided in entry->field contained invalid characters. Alternately,
               the parent field code was not found, or was already a metafield.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       GD_E_BAD_ENTRY
               There was an error in the specification of the field described by  entry,  or  the
               caller attempted to add a field of type RAW as a metafield.

       GD_E_BAD_INDEX
               The entry->fragment_index parameter was out of range.

       GD_E_BAD_TYPE
               The entry->data_type parameter provided with a RAW entry, or the entry->const_type
               parameter provided with a CONST or CARRAY entry, was invalid.

       GD_E_BOUNDS
               The entry->array_len parameter provided with  a  CARRAY  entry  was  greater  than
               GD_MAX_CARRAY_LENGTH.

       GD_E_DUPLICATE
               The  field  name  provided  in entry->field duplicated that of an already existing
               field.

       GD_E_INTERNAL_ERROR
               An internal error occurred in the library while trying to perform the task.   This
               indicates  a  bug  in  the  library.   Please  report  the incident to the GetData
               developers.

       GD_E_PROTECTED
               The metadata of the fragment was protected from change.  Or, the creation of a RAW
               field was attempted and the data of the fragment was protected.

       GD_E_RAW_IO
               An  I/O error occurred while creating an empty binary file to be associated with a
               newly added RAW field.

       GD_E_UNKNOWN_ENCODING
               The encoding scheme of the indicated format specification fragment is not known to
               the  library.   As a result, the library was unable to create an empty binary file
               to be associated with a newly added RAW field.

       GD_E_UNSUPPORTED
               The encoding scheme of  the  indicated  format  specification  fragment  does  not
               support  creating  an  empty  binary  file to be associated with a newly added RAW
               field.

       The dirfile error may be retrieved by calling gd_error(3).  A descriptive error string for
       the last error encountered can be obtained from a call to gd_error_string(3).

NOTES

       GetData  artifically  limits the number of elements in a CARRAY to the value of the symbol
       GD_MAX_CARRAY_LENGTH defined in getdata.h.  This is done to be  certain  that  the  CARRAY
       won't  overrun  the  line when flushed to disk.  On a 32-bit system, this number is 2**24.
       It is larger on a 64-bit system.

SEE ALSO

       gd_add_bit(3),  gd_add_carray(3),  gd_add_const(3),  gd_add_divide(3),   gd_add_lincom(3),
       gd_add_linterp(3),  gd_add_multiply(3), gd_add_phase(3), gd_add_polynom(3), gd_add_raw(3),
       gd_add_recip(3),   gd_add_sbit(3),    gd_add_spec(3),    gd_add_string(3),    gd_entry(3),
       gd_error(3),   gd_error_string(3),  gd_madd_bit(3),  gd_madd_carray(3),  gd_madd_const(3),
       gd_madd_divide(3),     gd_madd_lincom(3),     gd_madd_linterp(3),     gd_madd_multiply(3),
       gd_madd_phase(3),  gd_madd_polynom(3), gd_madd_recip(3), gd_madd_sbit(3), gd_madd_spec(3),
       gd_madd_string(3), gd_metaflush(3), gd_open(3), dirfile-format(5)