gd_alter_entry(3) GETDATA gd_alter_entry(3)NAMEgd_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 con‐
tain 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 be‐
low. 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-ze‐
ro, the binary file associated with the field will be converted for
changes in data type and samples-per-frame. If recode is zero, no bi‐
nary 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 en‐
try->comp_scal indicates whether the purely real scalar lists (en‐
try->a, or entry->b and entry->m) or the complex valued lists (en‐
try->ca, or entry->cb and entry->cm) will be used. The unused counter‐
parts 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 giv‐
en 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 re‐
tained. 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 mod‐
ified.
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 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 CAR‐
RAY 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 corresponding field parameter: if one al‐
ready existed, it is kept, otherwise the corresponding literal nu‐
merical parameter is used. If the value of the corresponding nu‐
merical 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 previ‐
ously 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 spe‐
cial value indicating no change listed above, GetData will de-ref‐
erence 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 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_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 protect‐
ed.
GD_E_RAW_IO
An I/O error occurred while translating the binary file associ‐
ated 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 frag‐
ment is not known to the library. As a result, the library was
unable to translate the binary file be associated with a modi‐
fied RAW field.
GD_E_UNSUPPORTED
The encoding scheme of the indicated format specification frag‐
ment 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 descrip‐
tive error string for the last error encountered can be obtained from a
call to gd_error_string(3).
SEE ALSOgd_alter_bit(3), gd_alter_carray(3), gd_alter_const(3), gd_alter_di‐
vide(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_re‐
cip(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.8.1 26 July 2012 gd_alter_entry(3)
