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->frag‐
       ment_index members are ignored by this function and need not be initialised.  All other members appropri‐
       ate 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).

       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.  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 re‐
       code 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 field parameters have special values which indicate no change  should  be  made  to  the  parameter.
       Specifically,  if  any  of  the  string  parameters, or the parameters (entry->a, entry->b, entry->m, en‐
       try->ca, entry->cb, or entry->cm) are NULL, the old values will be retained.  Similarly,  if  entry->spf,
       entry->n_fields,  or  entry->numbits  is  zero, or if entry->bitnum is -1, or if entry->data_type, or en‐
       try->const_type are equal to GD_NULL, these parameters will not be modified.

       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 para‐
           meter.  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 the empty string ("").  In this case, no change is made to the field code  for  the  corre‐
           sponding field parameter: if one already existed, it is kept, otherwise the corresponding literal nu‐
           merical  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.

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

RETURN VALUE

       On  success,  gd_alter_entry() returns 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 specified by field_code was not found.  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  re‐
               sult 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 pro‐
               vided with a CONST or CARRAY entry, was invalid.

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

SEE ALSO

       gd_alter_bit(3), gd_alter_carray(3), gd_alter_const(3),  gd_alter_divide(3),  gd_alter_lincom(3),  gd_al‐
       ter_linterp(3),  gd_alter_multiply(3),  gd_alter_phase(3),  gd_alter_polynom(3),  gd_alter_raw(3), gd_al‐
       ter_recip(3),  gd_alter_spec(3),  gd_delete(3),   gd_error(3),   gd_error_string(3),   gd_malter_spec(3),
       gd_metaflush(3), gd_move(3), gd_open(3), gd_rename(3), dirfile-format(5)

Version 0.7.0                                    3 November 2010                               gd_alter_entry(3)