Provided by: libgetdata-doc_0.11.0-4_all bug

NAME

       gd_alter_entry — modify the metadata of a Dirfile field

SYNOPSIS

       #include <getdata.h>

       int gd_alter_entry(DIRFILE *dirfile, const char *field_code, const gd_entry_t *entry, int
              recode);

DESCRIPTION

       The gd_alter_entry() function modifies the field specified by field_code  in  the  dirfile
       specified  by dirfile to correspond to the new parameters specified by entry.  In addition
       to specifying a regular field, field_code may also refer to a metafield by  specifying  it
       using  its  full  (slashed)  field  code.   However,  field_code  should  never  contain a
       representation suffix.

       The form of entry is described in detail in the get_entry(3) man page.   The  entry->field
       and   entry->fragment_index  members  are  ignored  by  this  function  and  need  not  be
       initialised.  All other members appropriate to the field  type  of  field_code  should  be
       initialised,  except  as  noted  below.   To  change  the  fragment  index of a field, use
       gd_move(3).  To change the name of a field, use gd_rename(3).

       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).

       If  field_code  specifies a RAW field and the recode argument is non-zero, the binary file
       associated with the field will be converted for changes  in  data  type  and  samples-per-
       frame.  In this case, the field's I/O pointer will be reset to the beginning-of-frame.  If
       recode is zero, no binary file conversion will take place.

       If field_code specifies a LINTERP field and the recode argument is non-zero,  the  look-up
       table  file  will be moved if entry->table specifies a different path.  If a file with the
       new pathname already exists, it will be overwritten.  If the field specified by field_code
       is of type other than RAW or LINTERP, the recode argument is ignored.

       If field_code specified a LINCOM or POLYNOM field, the value of entry->comp_scal indicates
       whether the purely real scalar lists (entry->a, or entry->b and entry->m) or  the  complex
       valued   lists  (entry->ca,  or  entry->cb  and  entry->cm)  will  be  used.   The  unused
       counterparts need not be initialised.

       The entry->field_type member must correspond  to  the  field  type  of  field_code.   This
       interface  cannot  be  used to change the type of a given field.  To do so, delete the old
       field first with gd_delete(3), and then create a  new  field  of  the  desired  type  with
       gd_add(3).

       Some  entry  members  have  special  values which indicate no change should be made to the
       member.  These special values are:

       NULL:   any of the string members;

       0:      spf, n_fields, numbits, cdividend, dividend, or array_len;

       -1:     bitnum or period;

       GD_NULL:
               data_type or const_type;

       GD_WINDOP_UNK:
               windop.

       All entry->scalar elements relevant for the given field type must be initialised to one of
       the following values:

       •   a  pointer  to  a  field  code  indicating  a  new  scalar  field  to  be used for the
           corresponding field parameter.  If the parameter was previously a literal  number,  it
           will be replaced by the specified field code.  If the parameter was previously a field
           code, the new field code will replace the old one.  If  the  field  code  specifies  a
           CARRAY field, the corresponding entry->scalar_ind element should also be set.

       •   a pointer to the empty string ("").  In this case, no change is made to the field code
           for the corresponding field parameter: if one already existed, it is  kept,  otherwise
           the  corresponding  literal  numerical  parameter  is  used.   If  the  value  of  the
           corresponding numerical entry member is the special value listed above  indicating  no
           change,  no  change  is made to the field parameter at all.  NB: In this case, GetData
           also ignores the corresponding entry->scalar_ind element, even if it differs from  the
           current  value.   To  change  a  scalar_ind element without changing the corresponding
           scalar, set that scalar element to its current value (at which point GetData  operates
           as per the previous bullet).

       •   the  NULL  pointer.  If the corresponding field parameter was previously a field code,
           the field code will be deleted and a literal number used instead.  In the special case
           when  a scalar element is NULL and the corresponding numerical entry member contains a
           special value indicating  no  change  listed  above,  GetData  will  de-reference  the
           previous  field  code  value  and convert it into a literal number before removing the
           field code from the entry.

       If this function is used to increase the length of a CARRAY field, the added elements will
       be uninitialised.  Use gd_put_carray_slice(3) or equivalent to initialise them.

RETURN VALUE

       On  success,  gd_alter_entry()  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 specified by field_code was not found or a supplied field code  did  not
               contain  the  appropriate  prefix  or  suffix.   This  error  may also result from
               attempting to dereference a scalar  field  code  which  indicates  a  non-existent
               field.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       GD_E_BAD_ENTRY
               One or more of the parameters specified in entry was invalid.

       GD_E_BAD_FIELD_TYPE
               The  entry->field_type  parameter  did  not  correspond  to  the type of the field
               specified by field_code, or an attempt was made  to  modify  the  immutable  INDEX
               field.   This  error may also result from attempting to dereference a scalar field
               code which does not indicate a CONST or CARRAY field.

       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_IO An I/O error occurred while translating the binary file associated with a modified
               RAW field, or an I/O error occurred while attempting to  rename  a  LINTERP  table
               file.

       GD_E_PROTECTED
               The  metadata  of  the  fragment  was  protected  from  change.   Or, a request to
               translate the binary file associated with a RAW field was attempted, but 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 translate the binary file  be
               associated with a modified RAW field.

       GD_E_UNSUPPORTED
               The  encoding  scheme  of  the  indicated  format  specification fragment does not
               support translating the binary file associated with a modified 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 function dirfile_alter_entry() appeared in GetData-0.5.0.

       In GetData-0.7.0, this function was renamed to gd_alter_entry().

       In GetData-0.8.0, the first version supporting fragment affixes, this function would apply
       the  destination  fragment's affixes to the supplied entry->field name.  In GetData-0.8.1,
       this changed: gd_alter_entry() now assumes entry->field  contains  the  full  field  name,
       including any necessary affixes.

       In GetData-0.10.0, the error return 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_alter_bit(3),      gd_alter_carray(3),      gd_alter_const(3),      gd_alter_divide(3),
       gd_alter_lincom(3),    gd_alter_linterp(3),    gd_alter_multiply(3),    gd_alter_phase(3),
       gd_alter_polynom(3),  gd_alter_raw(3),  gd_alter_recip(3), gd_alter_spec(3), gd_delete(3),
       gd_error(3),   gd_error_string(3),   gd_hidden(3),   gd_malter_spec(3),   gd_metaflush(3),
       gd_move(3), gd_open(3), gd_put_carray_slice(3), gd_rename(3), dirfile-format(5)