1
2
3
4
5
6
7
8
9gd_alter_entry(3)                   GETDATA                  gd_alter_entry(3)
10
11
12

NAME

14       gd_alter_entry — modify the metadata of a Dirfile field
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       int gd_alter_entry(DIRFILE *dirfile, const char *field_code, const
21              gd_entry_t *entry, int recode);
22
23

DESCRIPTION

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
32       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
39       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
45       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
51       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
57       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
63       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
68       Some  entry members have special values which indicate no change should
69       be made to the member.  These special values are:
70
71       NULL:   any of the string members;
72
73       0:      spf, n_fields, numbits, cdividend, dividend, or array_len;
74
75       -1:     bitnum or period;
76
77       GD_NULL:
78               data_type or const_type;
79
80       GD_WINDOP_UNK:
81               windop.
82
83       All entry->scalar elements relevant for the given field  type  must  be
84       initialised to one of the following values:
85
86       ·   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
94       ·   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
106       ·   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
114       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
118

RETURN VALUE

120       On success, gd_alter_entry() return zero.   On error, a negative-valued
121       error code is returned.  Possible error codes are:
122
123       GD_E_ACCMODE
124               The specified dirfile was opened read-only.
125
126       GD_E_ALLOC
127               The library was unable to allocate memory.
128
129       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
135       GD_E_BAD_DIRFILE
136               The supplied dirfile was invalid.
137
138       GD_E_BAD_ENTRY
139               One or more of the parameters specified in entry was invalid.
140
141       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
148       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
153       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
157       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
163       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
169       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
174       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
179

HISTORY

181       The function dirfile_alter_entry() appeared in GetData-0.5.0.
182
183       In GetData-0.7.0, this function was renamed to gd_alter_entry().
184
185       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
191       In GetData-0.10.0, the error return changed from -1 to a  negative-val‐
192       ued error code.
193
194       See gd_entry(3) for the history of the gd_entry_t structure.
195
196

SEE ALSO

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)
205
206
207
208Version 0.10.0                 25 December 2016              gd_alter_entry(3)
Impressum