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

NAME

14       gd_add_bit,  gd_add_carray  gd_add_clincom, gd_add_const, gd_add_cpoly‐
15       nom,   gd_add_crecip,   gd_add_divide,   gd_add_indir,   gd_add_lincom,
16       gd_add_linterp,    gd_add_multiply,    gd_add_phase,    gd_add_polynom,
17       gd_add_raw, gd_add_recip,  gd_add_sarray,  gd_add_sbit,  gd_add_sindir,
18       gd_add_string — add a field to a Dirfile
19
20

SYNOPSIS

22       #include <getdata.h>
23
24       int gd_add_bit(DIRFILE *dirfile, const char *field_name, const char
25              *in_field, int bitnum, int numbits, int fragment_index);
26
27       int gd_add_carray(DIRFILE *dirfile, const char *field_name, gd_type_t
28              const_type, size_t array_len, gd_type_t data_type, void *value,
29              int fragment_index);
30
31       int gd_add_clincom(DIRFILE *dirfile, const char *field_name, int
32              n_fields, const char **in_fields, const double complex *cm,
33              const double complex *cb, int fragment_index);
34
35       int gd_add_const(DIRFILE *dirfile, const char *field_name, gd_type_t
36              const_type, gd_type_t data_type, void *value, int
37              fragment_index);
38
39       int gd_add_cpolynom(DIRFILE *dirfile, const char *field_name, int
40              poly_ord, const char *in_fields, const double complex *ca, int
41              fragment_index);
42
43       int gd_add_crecip(DIRFILE *dirfile, const char *field_name, const char
44              *in_field, double complex cdividend, int fragment_index);
45
46       int gd_add_divide(DIRFILE *dirfile, const char *field_name, const char
47              *in_field1, const char *in_field2, int fragment_index);
48
49       int gd_add_indir(DIRFILE *dirfile, const char *field_name, const char
50              *index_field, const char *carray_field, int fragment_index);
51
52       int gd_add_lincom(DIRFILE *dirfile, const char *field_name, int
53              n_fields, const char **in_fields, const double *m, const double
54              *b, int fragment_index);
55
56       int gd_add_linterp(DIRFILE *dirfile, const char *field_name, const char
57              *in_field, const char *table, int fragment_index);
58
59       int gd_add_mplex(DIRFILE *dirfile, const char *field_name, const char
60              *in_field, const char *count_field, int count_val, int period,
61              int fragment_index);
62
63       int gd_add_multiply(DIRFILE *dirfile, const char *field_name, const
64              char *in_field1, const char *in_field2, int fragment_index);
65
66       int gd_add_phase(DIRFILE *dirfile, const char *field_name, const char
67              *in_field, gd_int64_t shift, int fragment_index);
68
69       int gd_add_polynom(DIRFILE *dirfile, const char *field_name, int
70              poly_ord, const char *in_fields, const double *a, int
71              fragment_index );
72
73       int gd_add_raw(DIRFILE *dirfile, const char *field_name, gd_type_t
74              data_type, unsigned int spf, int fragment_index);
75
76       int gd_add_recip(DIRFILE *dirfile, const char *field_name, const char
77              *in_field, double dividend, int fragment_index);
78
79       int gd_add_sarray(DIRFILE *dirfile, const char *field_name, size_t
80              array_len, const char **values,int fragment_index);
81
82       int gd_add_sbit(DIRFILE *dirfile, const char *field_name, const char
83              *in_field, int bitnum, int numbits, int fragment_index);
84
85       int gd_add_sindir(DIRFILE *dirfile, const char *field_name, const char
86              *index_field, const char *sarray_field, int fragment_index);
87
88       int gd_add_string(DIRFILE *dirfile, const char *field_name, const char
89              *value, int fragment_index);
90
91       int gd_add_window(DIRFILE *dirfile, const char *field_name, const char
92              *in_field, const char *check_field, gd_windop_t windop,
93              gd_triplet_t threshold, int fragment_index);
94
95

DESCRIPTION

97       These  functions  provide  alternatives  to  using  the  gd_add(3)   or
98       gd_add_spec(3)  functions  to  add a new field of the indicated type to
99       the dirfile specified by dirfile.
100
101       In all of these calls, field_name indicates the name of the field to be
102       added.   Further,  fragment_index is the index of the format specifica‐
103       tion fragment into which the field should  be  added.   (To  convert  a
104       fragment  index to its file name, see gd_fragmentname(3).)  The meaning
105       and  allowed  types  of  other  arguments  may  be  obtained  from  the
106       gd_entry(3) and dirfile-format(5) manual pages.
107
108       The  gd_add_clincom()  and gd_add_cpolynom() functions are identical to
109       gd_add_lincom() and gd_add_polynom(), except they take  complex  scalar
110       parameters, instead of purely real values.
111
112       The  gd_add_lincom()  and  gd_add_clincom() functions takes pointers to
113       three arrays of  length  n_fields  containing  the  input  field  names
114       (in_fields),  the  gain  factors  (m or cm), and the offset terms (b or
115       cb).  Similarly, gd_add_polynom() and gd_add_cpolynom() take  an  array
116       of  length  poly_ord  + 1 containing the polynomial co-efficients (a or
117       ca).
118
119       The    gd_add_carray(),    gd_add_const(),     gd_add_sarray(),     and
120       gd_add_string()  functions add the field and set the value of the field
121       to value.  For gd_add_const() and gd_add_carray(), the const_type argu‐
122       ment  specifies  the storage type for the const, while data_type speci‐
123       fies  the  data  type  of  the  value  pointed  to   by   value.    For
124       gd_add_sarray(), value should be an array of array_len string pointers.
125
126       The  gd_int64_t type is a signed 64-bit integer type.  The gd_triplet_t
127       type is defined as:
128
129           typedef union {
130             gd_int64_t i;
131             gd_uint64_t u;
132             double r;
133           } gd_triplet_t;
134
135       Which element of this gd_triplet_t union to set depends on the operator
136       selected for the WINDOW field.  See gd_entry(3) for details.
137
138       A  metafield  may be added to the dirfile either by calling these func‐
139       tions  with  field_name   containing   the   fully   formed   "<parent-
140       field>/<meta-field>"  field  code,  or  else by using the corresponding
141       gd_madd_...()  function  (see  gd_madd_bit(3),  &c.)  When   adding   a
142       metafield  with  these functions, fragment_index is ignored and GetData
143       will add the new metafield to the same format specification fragment in
144       which  the parent field is defined.  If the specified parent field name
145       is an alias, the canonical name of the field will be substituted.
146
147       All fields added with this interface must contain  literal  parameters.
148       Fields  with  scalar  fields  as  parameters cannot be added with these
149       functions.   Those   fields   must   be   added   with   gd_add(3)   or
150       gd_add_spec(3).
151
152       See   NOTES   below   for   information   on   using  gd_add_clincom(),
153       gd_add_cpolynom(), and gd_add_crecip() in the C89 GetData API.
154
155

RETURN VALUE

157       On success, any of these functions returns zero.   On  error,  a  nega‐
158       tive-valued error value is returned.  Possible error values are:
159
160       GD_E_ACCMODE
161               The specified dirfile was opened read-only.
162
163       GD_E_ALLOC
164               The library was unable to allocate memory.
165
166       GD_E_BAD_CODE
167               The  field_name contained invalid characters; or it or an input
168               field did not contain the affected fragment's prefix or suffix.
169
170       GD_E_BAD_DIRFILE
171               The supplied dirfile was invalid.
172
173       GD_E_BAD_ENTRY
174               One or more of the field parameters specified was invalid.
175
176       GD_E_BAD_INDEX
177               The fragment_index argument was out of range.
178
179       GD_E_BAD_TYPE
180               The data_type or const_type argument provided  to  gd_add_raw()
181               or gd_add_const() was invalid.
182
183       GD_E_DUPLICATE
184               The  field_name provided duplicated that of an already existing
185               field.
186
187       GD_E_INTERNAL_ERROR
188               An internal error occurred in the library while trying to  per‐
189               form  the  task.   This indicates a bug in the library.  Please
190               report the incident to the GetData developers.
191
192       GD_E_IO (gd_add_raw() only)  An I/O error occurred  while  creating  an
193               empty  binary  file  to  be  associated  with a newly added RAW
194               field.
195
196       GD_E_PROTECTED
197               The metadata of the fragment was protected  from  change.   Or,
198               the  creation  of a RAW field was attempted and the data of the
199               fragment was protected.
200
201       GD_E_UNKNOWN_ENCODING
202               (gd_add_raw() only) The encoding scheme of the indicated format
203               specification  fragment  is not known to the library.  As a re‐
204               sult, the library was unable to create an empty binary file  to
205               be associated with a newly added RAW field.
206
207       GD_E_UNSUPPORTED
208               (gd_add_raw() only) The encoding scheme of the indicated format
209               specification fragment does not support creating an empty bina‐
210               ry file to be associated with a newly added RAW field.
211
212       The  dirfile error may also be retrieved by calling gd_error(3).  A de‐
213       scriptive error string for the last error encountered can  be  obtained
214       from a call to gd_error_string(3).
215
216

NOTES

218       The C89 GetData API provides different prototypes for gd_add_clincom(),
219       gd_add_cpolynom(), and gd_add_crecip():
220
221       #define GD_C89_API
222       #include <getdata.h>
223
224       int gd_add_clincom(DIRFILE *dirfile, const char *field_name, int
225              n_fields, const char **in_fields, const double *cm, const double
226              *cb, int fragment_index);
227
228       int gd_add_cpolynom(DIRFILE *dirfile, const char *field_name, int
229              poly_ord, const char *in_fields, const double *ca, int
230              fragment_index);
231
232       int gd_add_crecip(DIRFILE *dirfile, const char *field_name, const char
233              *in_field, const double cdividend[2], int fragment_index);
234
235       In  this  case,  the  array pointers passed as cm, cb or ca should have
236       twice as many (purely real) elements, consisting  of  alternating  real
237       and  imaginary parts for the complex data.  That is, for example, ca[0]
238       should be the real part of the first co-efficient, ca[1] the  imaginary
239       part  of  the first co-efficient, ca[2] the real part of the second co-
240       efficient, ca[3] the imaginary part of the second co-efficient, and  so
241       on.   Similarly, the cdividend parameter becomes a double precision ar‐
242       ray of length two.
243
244       For gd_add_clincom() and gd_add_cpolynom(), these are simply  different
245       (but  equivalent)  declarations  of  the C99 function entry point.  For
246       gd_add_crecip(), however, a different entry point is needed (since  the
247       cdividend  parameter  is  passed by reference instead of by value).  In
248       the interests of portability, the C89 version of gd_add_crecip() is al‐
249       ways  available, and may be accessed as gd_add_crecip89(), with the C89
250       prototype, in both the C99 and C89 APIs.
251
252

HISTORY

254       The       functions       dirfile_add_bit(),       dirfile_add_const(),
255       dirfile_add_lincom(),   dirfile_add_linterp(),  dirfile_add_multiply(),
256       dirfile_add_phase(), dirfile_add_raw(),  and  dirfile_add_string()  ap‐
257       peared in GetData-0.4.0.
258
259       The     functions     dirfile_add_clincom(),    dirfile_add_cpolynom(),
260       dirfile_add_polynom(),  and  dirfile_add_sbit()  appeared   in   GetDa‐
261       ta-0.6.0.
262
263       In   GetData-0.7.0,   the   functions  were  renamed  to  gd_add_bit(),
264       gd_add_clincom(), gd_add_const(),  gd_add_cpolynom(),  gd_add_lincom(),
265       gd_add_linterp(),  gd_add_multiply(), gd_add_phase(), gd_add_polynom(),
266       gd_add_raw(),  gd_add_sbit(),  and  gd_add_string().    The   functions
267       gd_add_carray(),  gd_add_crecip(),  gd_add_divide(), and gd_add_recip()
268       also appeared in this version.
269
270       In GetData-0.8.0, these functions first allowed  adding  metafields  by
271       providing  the full (slashed) field name.  The functions gd_add_mplex()
272       and gd_add_window() also appeared in this version.
273
274       In GetData-0.10.0, the error return from these functions  changed  from
275       -1  to  a  negative-valued  error  code.  The functions gd_add_indir(),
276       gd_add_sarray(), and gd_add_sindir() also appeared in this version.
277
278

SEE ALSO

280       gd_add(3),       gd_add_spec(3),       gd_entry(3),        gd_error(3),
281       gd_error_string(3),  the  corresponding  gd_madd_<entry-type> functions
282       (e.g.  gd_madd_bit(3)), gd_metaflush(3), gd_open(3), dirfile-format(5)
283
284
285
286Version 0.10.0                 25 December 2016                  gd_add_bit(3)
Impressum