gd_alter_entry(3)						      GETDATA							 gd_alter_entry(3)

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 pa-
       rameters 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 pa-
       rameters, 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->con-
       st_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  previ-
	   ously  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 al-
	   ready existed, it is kept, otherwise the corresponding literal numerical parameter is used.	If the value of the corresponding  numeri-
	   cal 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 num-
	   ber 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 er-
       ror 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 mod-
	       ify  the immutable INDEX field.	This error may also result from attempting to dereference a scalar field code which does not indi-
	       cate 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  at-
	       tempting 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 un-
	       able 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_er-
       ror_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)