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.