1gd_add_bit(3) GETDATA gd_add_bit(3)
10
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
22 #include <getdata.h>
23 int gd_add_bit(DIRFILE *dirfile, const char *field_name, const char
25 *in_field, int bitnum, int numbits, int fragment_index);
26 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 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 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 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 int gd_add_crecip(DIRFILE *dirfile, const char *field_name, const char
44 *in_field, double complex cdividend, int fragment_index);
45 int gd_add_divide(DIRFILE *dirfile, const char *field_name, const char
47 *in_field1, const char *in_field2, int fragment_index);
48 int gd_add_indir(DIRFILE *dirfile, const char *field_name, const char
50 *index_field, const char *carray_field, int fragment_index);
51 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 int gd_add_linterp(DIRFILE *dirfile, const char *field_name, const char
57 *in_field, const char *table, int fragment_index);
58 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 int gd_add_multiply(DIRFILE *dirfile, const char *field_name, const
64 char *in_field1, const char *in_field2, int fragment_index);
65 int gd_add_phase(DIRFILE *dirfile, const char *field_name, const char
67 *in_field, gd_int64_t shift, int fragment_index);
68 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 int gd_add_raw(DIRFILE *dirfile, const char *field_name, gd_type_t
74 data_type, unsigned int spf, int fragment_index);
75 int gd_add_recip(DIRFILE *dirfile, const char *field_name, const char
77 *in_field, double dividend, int fragment_index);
78 int gd_add_sarray(DIRFILE *dirfile, const char *field_name, size_t
80 array_len, const char **values,int fragment_index);
81 int gd_add_sbit(DIRFILE *dirfile, const char *field_name, const char
83 *in_field, int bitnum, int numbits, int fragment_index);
84 int gd_add_sindir(DIRFILE *dirfile, const char *field_name, const char
86 *index_field, const char *sarray_field, int fragment_index);
87 int gd_add_string(DIRFILE *dirfile, const char *field_name, const char
89 *value, int fragment_index);
90 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
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 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 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 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 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 The gd_int64_t type is a signed 64-bit integer type. The gd_triplet_t
127 type is defined as:
128 typedef union {
130 gd_int64_t i;
131 gd_uint64_t u;
132 double r;
133 } gd_triplet_t;
134 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 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 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 See NOTES below for information on using gd_add_clincom(),
153 gd_add_cpolynom(), and gd_add_crecip() in the C89 GetData API.
154
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 GD_E_ACCMODE
161 The specified dirfile was opened read-only.
162 GD_E_ALLOC
164 The library was unable to allocate memory.
165 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 GD_E_BAD_DIRFILE
171 The supplied dirfile was invalid.
172 GD_E_BAD_ENTRY
174 One or more of the field parameters specified was invalid.
175 GD_E_BAD_INDEX
177 The fragment_index argument was out of range.
178 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 GD_E_DUPLICATE
184 The field_name provided duplicated that of an already existing
185 field.
186 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 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 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 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 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 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
218 The C89 GetData API provides different prototypes for gd_add_clincom(),
219 gd_add_cpolynom(), and gd_add_crecip():
220 #define GD_C89_API
222 #include <getdata.h>
223 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 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 int gd_add_crecip(DIRFILE *dirfile, const char *field_name, const char
233 *in_field, const double cdividend[2], int fragment_index);
234 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 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
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 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 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 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 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
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)
283Version 0.10.0 25 December 2016 gd_add_bit(3)