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)