Ubuntu Manpage: gd_alter_entry — modify the metadata of a Dirfile field

Provided by: libgetdata-doc_0.11.0-3ubuntu1_all

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

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:

• 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 to 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. NB: In this case, GetData
also ignores the corresponding entry->scalar_ind element, even if it differs from the
current value. To change a scalar_ind element without changing the corresponding
scalar, set that scalar element to its current value (at which point GetData operates
as per the previous bullet).

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

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.

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

HISTORY

SEE ALSO