gd_alter_entry man page

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

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:

NULL:

any of the string members;

0:

spf, n_fields, numbits, cdividend, dividend, or array_len;

-1:

bitnum or period;

GD_NULL:

data_type or const_type;

GD_WINDOP_UNK:

windop.

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.

Return Value

On success, gd_alter_entry() return zero.   On error, a negative-valued error code is returned.  Possible error codes 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_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_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_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 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).

History

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.

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

Referenced By

dirfile-encoding(5), gd_alter_bit(3), gd_getdata(3), gd_hide(3).

25 December 2016 Version 0.10.0 GETDATA