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.

       The only flags in the entry->flags member which are honoured are GD_EN_HIDDEN, which  should  be  set  or
       cleared  to  set  the  hiddenness  of  the  entry (see gd_hidden(3)), and GD_EN_COMPSCAL, which indicates
       whether scalar parameters are initialised from the complex valued or purely real member, which  both  are
       present (LINCOM, POLYNOM, RECIP).

       A  metafield  may  be added either by calling gd_madd() with entry->field containing only the metafield's
       name, or else by calling gd_add() with the  fully  formed  "<parent-field>/<meta-field>"  field  code  in
       entry->field.   Regardless  of  which  interface  is  used,  when adding a metafield the value of entry->
       fragment_index is ignored and GetData will add  the  new  metafield  to  the  same  format  specification
       fragment  in  which  the  parent  field  is defined.  If the specified parent field name is an alias, the
       canonical name of the field will be substituted.

       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, a negative-valued error code is returned.
       Possible error codes 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; or it or an input field did
               not  contain the affected fragment's prefix or suffix. 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_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_IO An I/O error occurred while creating an empty binary file to be associated with a newly added RAW
               field.

       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_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 error code is also stored in the DIRFILE object and may be retrieved after this function  returns  by
       calling   gd_error(3).    A   descriptive  error  string  for  the  error  may  be  obtained  by  calling
       gd_error_string(3).

HISTORY

       The functions dirfile_add() and dirfile_madd() appeared in GetData-0.4.0.

       In GetData-0.7.0, the functions were renamed to gd_add() and gd_madd().

       In GetData-0.8.0, gd_add() first allowed adding metafields by providing the full  (slashed)  field  name.
       This  was  the  first  version supporting fragment affixes, and in this version, gd_add() would apply the
       destination fragment's affixes to the  supplied  entry->field  name.   In  GetData-0.8.1,  this  changed:
       gd_add() now assumes entry->field contains the full field name, including any necessary affixes.

       In GetData-0.10.0, the error return from these functions changed from -1 to a negative-valued error code.

       See gd_entry(3) for the history of the gd_entry_t structure.

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)