1gd_alter_entry(3) GETDATA gd_alter_entry(3)
10
14 gd_alter_entry — modify the metadata of a Dirfile field
15
18 #include <getdata.h>
19 int gd_alter_entry(DIRFILE *dirfile, const char *field_code, const
21 gd_entry_t *entry, int recode);
22
25 The gd_alter_entry() function modifies the field specified by
26 field_code in the dirfile specified by dirfile to correspond to the new
27 parameters specified by entry. In addition to specifying a regular
28 field, field_code may also refer to a metafield by specifying it using
29 its full (slashed) field code. However, field_code should never con‐
30 tain a representation suffix.
31 The form of entry is described in detail in the get_entry(3) man page.
33 The entry->field and entry->fragment_index members are ignored by this
34 function and need not be initialised. All other members appropriate to
35 the field type of field_code should be initialised, except as noted be‐
36 low. To change the fragment index of a field, use gd_move(3). To
37 change the name of a field, use gd_rename(3).
38 The only flags in the entry->flags member which are honoured are
40 GD_EN_HIDDEN, which should be set or cleared to set the hiddenness of
41 the entry (see gd_hidden(3)), and GD_EN_COMPSCAL, which indicates
42 whether scalar parameters are initialised from the complex valued or
43 purely real member, which both are present (LINCOM, POLYNOM, RECIP).
44 If field_code specifies a RAW field and the recode argument is non-ze‐
46 ro, the binary file associated with the field will be converted for
47 changes in data type and samples-per-frame. In this case, the field's
48 I/O pointer will be reset to the beginning-of-frame. If recode is ze‐
49 ro, no binary file conversion will take place.
50 If field_code specifies a LINTERP field and the recode argument is non-
52 zero, the look-up table file will be moved if entry->table specifies a
53 different path. If a file with the new pathname already exists, it
54 will be overwritten. If the field specified by field_code is of type
55 other than RAW or LINTERP, the recode argument is ignored.
56 If field_code specified a LINCOM or POLYNOM field, the value of entry->
58 comp_scal indicates whether the purely real scalar lists (entry->a, or
59 entry->b and entry->m) or the complex valued lists (entry->ca, or en‐
60 try->cb and entry->cm) will be used. The unused counterparts need not
61 be initialised.
62 The entry->field_type member must correspond to the field type of
64 field_code. This interface cannot be used to change the type of a giv‐
65 en field. To do so, delete the old field first with gd_delete(3), and
66 then create a new field of the desired type with gd_add(3).
67 Some entry members have special values which indicate no change should
69 be made to the member. These special values are:
70 NULL: any of the string members;
72 0: spf, n_fields, numbits, cdividend, dividend, or array_len;
74 -1: bitnum or period;
76 GD_NULL:
78 data_type or const_type;
79 GD_WINDOP_UNK:
81 windop.
82 All entry->scalar elements relevant for the given field type must be
84 initialised to one of the following values:
85 · a pointer to a field code indicating a new scalar field to be used
87 for the corresponding field parameter. If the parameter was previ‐
88 ously a literal number, it will be replaced by the specified field
89 code. If the parameter was previously a field code, the new field
90 code will replace the old one. If the field code specifies a
91 CARRAY field, the corresponding entry->scalar_ind element should
92 also be set.
93 · a pointer to the empty string (""). In this case, no change is
95 made to the field code for the corresponding field parameter: if
96 one already existed, it is kept, otherwise the corresponding liter‐
97 al numerical parameter is used. If the value of the corresponding
98 numerical entry member is the special value listed above indicating
99 no change, no change is made to the field parameter at all. NB: In
100 this case, GetData also ignores the corresponding entry->scalar_ind
101 element, even if it differs from the current value. To change a
102 scalar_ind element without changing the corresponding scalar, set
103 that scalar element to its current value (at which point GetData
104 operates as per the previous bullet).
105 · the NULL pointer. If the corresponding field parameter was previ‐
107 ously a field code, the field code will be deleted and a literal
108 number used instead. In the special case when a scalar element is
109 NULL and the corresponding numerical entry member contains a spe‐
110 cial value indicating no change listed above, GetData will de-ref‐
111 erence the previous field code value and convert it into a literal
112 number before removing the field code from the entry.
113 If this function is used to increase the length of a CARRAY field, the
115 added elements will be uninitialised. Use gd_put_carray_slice(3) or
116 equivalent to initialise them.
117
120 On success, gd_alter_entry() return zero. On error, a negative-valued
121 error code is returned. Possible error codes are:
122 GD_E_ACCMODE
124 The specified dirfile was opened read-only.
125 GD_E_ALLOC
127 The library was unable to allocate memory.
128 GD_E_BAD_CODE
130 The field specified by field_code was not found or a supplied
131 field code did not contain the appropriate prefix or suffix.
132 This error may also result from attempting to dereference a
133 scalar field code which indicates a non-existent field.
134 GD_E_BAD_DIRFILE
136 The supplied dirfile was invalid.
137 GD_E_BAD_ENTRY
139 One or more of the parameters specified in entry was invalid.
140 GD_E_BAD_FIELD_TYPE
142 The entry->field_type parameter did not correspond to the type
143 of the field specified by field_code, or an attempt was made to
144 modify the immutable INDEX field. This error may also result
145 from attempting to dereference a scalar field code which does
146 not indicate a CONST or CARRAY field.
147 GD_E_BAD_TYPE
149 The entry->data_type parameter provided with a RAW entry, or
150 the entry->const_type parameter provided with a CONST or CARRAY
151 entry, was invalid.
152 GD_E_IO An I/O error occurred while translating the binary file associ‐
154 ated with a modified RAW field, or an I/O error occurred while
155 attempting to rename a LINTERP table file.
156 GD_E_PROTECTED
158 The metadata of the fragment was protected from change. Or, a
159 request to translate the binary file associated with a RAW
160 field was attempted, but the data of the fragment was protect‐
161 ed.
162 GD_E_UNKNOWN_ENCODING
164 The encoding scheme of the indicated format specification frag‐
165 ment is not known to the library. As a result, the library was
166 unable to translate the binary file be associated with a modi‐
167 fied RAW field.
168 GD_E_UNSUPPORTED
170 The encoding scheme of the indicated format specification frag‐
171 ment does not support translating the binary file associated
172 with a modified RAW field.
173 The error code is also stored in the DIRFILE object and may be re‐
175 trieved after this function returns by calling gd_error(3). A descrip‐
176 tive error string for the error may be obtained by calling
177 gd_error_string(3).
178
181 The function dirfile_alter_entry() appeared in GetData-0.5.0.
182 In GetData-0.7.0, this function was renamed to gd_alter_entry().
184 In GetData-0.8.0, the first version supporting fragment affixes, this
186 function would apply the destination fragment's affixes to the supplied
187 entry->field name. In GetData-0.8.1, this changed: gd_alter_entry()
188 now assumes entry->field contains the full field name, including any
189 necessary affixes.
190 In GetData-0.10.0, the error return changed from -1 to a negative-val‐
192 ued error code.
193 See gd_entry(3) for the history of the gd_entry_t structure.
195
198 gd_alter_bit(3), gd_alter_carray(3), gd_alter_const(3),
199 gd_alter_divide(3), gd_alter_lincom(3), gd_alter_linterp(3),
200 gd_alter_multiply(3), gd_alter_phase(3), gd_alter_polynom(3),
201 gd_alter_raw(3), gd_alter_recip(3), gd_alter_spec(3), gd_delete(3),
202 gd_error(3), gd_error_string(3), gd_hidden(3), gd_malter_spec(3),
203 gd_metaflush(3), gd_move(3), gd_open(3), gd_put_carray_slice(3),
204 gd_rename(3), dirfile-format(5)
205Version 0.10.0 25 December 2016 gd_alter_entry(3)