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:
- •
- 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 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.
- •
- 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)