gd_alter_entry—modify the metadata of a Dirfile field


#include <getdata.h>

int gd_alter_entry(DIRFILE *dirfile, const char *field_code, const gd_entry_t *entry, int recode);


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

The only flags in the entry->flags member which are honoured are GD_EN_HIDDEN, which should be set or cleared to set the hiddenness of the entry (see gd_hidden(3)), and GD_EN_COMPSCAL, which indicates whether scalar parameters are initialised from the complex valued or purely real member, which both are present (LINCOM, POLYNOM, RECIP).

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. In this case, the field's I/O pointer will be reset to the beginning-of-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 entry members have special values which indicate no change should be made to the member. These special values are:

any of the string members;
spf, n_fields, numbits, cdividend, dividend, or array_len;
bitnum or period;
data_type or const_type;

All entry->scalar elements relevant for the given field type must be initialised to one of the following values:

If this function is used to increase the length of a CARRAY field, the added elements will be uninitialised. Use gd_put_carray_slice(3) or equivalent to initialise them.


On success, gd_alter_entry() return zero. On error, a negative-valued error code is returned. Possible error codes are:

The specified dirfile was opened read-only.
The library was unable to allocate memory.
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.
The supplied dirfile was invalid.
One or more of the parameters specified in entry was invalid.
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.
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.
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.
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.
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.
The encoding scheme of the indicated format specification fragment does not support translating the binary file associated with a modified RAW field.

The error code is also stored in the DIRFILE object and may be retrieved after this function returns by calling gd_error(3). A descriptive error string for the error may be obtained by calling gd_error_string(3).


The function dirfile_alter_entry() appeared in GetData-0.5.0.

In GetData-0.7.0, this function was renamed to gd_alter_entry().

In GetData-0.8.0, the first version supporting fragment affixes, this function would apply the destination fragment's affixes to the supplied entry->field name. In GetData-0.8.1, this changed: gd_alter_entry() now assumes entry->field contains the full field name, including any necessary affixes.

In GetData-0.10.0, the error return changed from −1 to a negative-valued error code.

See gd_entry(3) for the history of the gd_entry_t structure.


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_hidden(3), gd_malter_spec(3), gd_metaflush(3), gd_move(3), gd_open(3), gd_put_carray_slice(3), gd_rename(3), dirfile-format(5)

Last updated on 25 December 2016 for GetData Version 0.10.0.