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)