Provided by: libgetdata-dev_0.7.3-6_i386 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).

       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 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 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, entry->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  entry->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:

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

       o   a pointer 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.

       o   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 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_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_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_malter_spec(3),  gd_metaflush(3),
       gd_move(3), gd_open(3), gd_rename(3), dirfile-format(5)