gd_alter_entry—modify the metadata of a Dirfile field
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:
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 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)