gd_madd_phase(3)

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

NAME

14       gd_madd_bit,     gd_madd_carray,     gd_madd_clincom,    gd_madd_const,
15       gd_madd_cpolynom,   gd_madd_crecip,   gd_madd_divide,    gd_madd_indir,
16       gd_madd_lincom,   gd_madd_linterp,   gd_madd_multiply,   gd_madd_phase,
17       gd_madd_polynom,    gd_madd_recip,    gd_madd_sarray,     gd_madd_sbit,
18       gd_madd_sindir, gd_madd_string — add a field to a Dirfile
19
20

SYNOPSIS

22       #include <getdata.h>
23
24       int gd_madd_bit(DIRFILE *dirfile, const char *parent, const char
25              *field_name, const char *in_field, int bitnum, int numbits);
26
27       int gd_madd_carray(DIRFILE *dirfile, const char *parent, const char
28              *field_name, gd_type_t const_type, size_t array_len, gd_type_t
29              data_type, void *value);
30
31       int gd_madd_clincom(DIRFILE *dirfile, const char *parent, const char
32              *field_name, int n_fields, const char **in_fields, const double
33              complex *cm, const double complex *cb);
34
35       int gd_madd_const(DIRFILE *dirfile, const char *parent, const char
36              *field_name, gd_type_t const_type, gd_type_t data_type, void
37              *value);
38
39       int gd_madd_cpolynom(DIRFILE *dirfile, const char *parent, const char
40              *field_name, int poly_ord, const char *in_field, const double
41              complex *ca);
42
43       int gd_madd_crecip(DIRFILE *dirfile, const char *parent, const char
44              *field_name, const char *in_field, double complex cdividend, int
45              fragment_index);
46
47       int gd_madd_divide(DIRFILE *dirfile, const char *parent, const char
48              *field_name,  const char *in_field1, const char *in_field2);
49
50       int gd_madd_indir(DIRFILE *dirfile, const char *parent, const char
51              *field_name,  const char *index_field, const char
52              *carray_field);
53
54       int gd_madd_lincom(DIRFILE *dirfile, const char *parent, const char
55              *field_name, int n_fields, const char **in_fields, const double
56              *m, const double *b);
57
58       int gd_madd_linterp(DIRFILE *dirfile, const char *parent, const char
59              *field_name, const char *in_field, const char *table);
60
61       int gd_madd_mplex(DIRFILE *dirfile, const char *parent, const char
62              *field_name, const char *in_field, const char *count_field, int
63              count_val, int period);
64
65       int gd_madd_multiply(DIRFILE *dirfile, const char *parent, const char
66              *field_name,  const char *in_field1, const char *in_field2);
67
68       int gd_madd_polynom(DIRFILE *dirfile, const char *parent, const char
69              *field_name, int poly_ord, const char *in_field, const double
70              *a);
71
72       int gd_madd_phase(DIRFILE *dirfile, const char *parent, const char
73              *field_name, const char *in_field, gd_int64_t shift);
74
75       int gd_madd_recip(DIRFILE *dirfile, const char *parent, const char
76              *field_name, const char *in_field, double dividend, int
77              fragment_index);
78
79       int gd_madd_sarray(DIRFILE *dirfile, const char *parent, const char
80              *field_name, size_t array_len ,constchar**"value);
81
82       int gd_madd_sbit(DIRFILE *dirfile, const char *parent, const char
83              *field_name, const char *in_field, int bitnum, int numbits);
84
85       int gd_madd_sindir(DIRFILE *dirfile, const char *parent, const char
86              *field_name,  const char *index_field, const char
87              *sarray_field);
88
89       int gd_madd_string(DIRFILE *dirfile, const char *parent, const char
90              *field_name, const char *value);
91
92       int gd_madd_window(DIRFILE *dirfile, const char *parent, const char
93              *field_name, const char *in_field, const char *check_field,
94              gd_windop_t windop, gd_triplet_t threshold);
95
96

DESCRIPTION

98       These  functions  add  a  new metafield of the indicated type under the
99       parent field given by parent to the dirfile specified by dirfile.
100
101       In all of these calls, field_name indicates the name of the field to be
102       added.   It  should  not  be the full <parent-field>/<meta-field> field
103       code.  The meaning and valid types of other arguments may  be  obtained
104       from the gd_entry(3) and dirfile-format(5) manual pages.
105
106       The gd_madd_clincom() and gd_madd_cpolynom() functions are identical to
107       gd_madd_lincom() and gd_madd_polynom(), except they take complex scalar
108       parameters, instead of purely real values.
109
110       The  gd_madd_lincom()  and gd_madd_clincom() functions take pointers to
111       three arrays of  length  n_fields  containing  the  input  field  names
112       (in_fields),  the  gain  factors  (m or cm), and the offset terms (b or
113       cb).  Similarly, gd_madd_polynom() and gd_madd_cpolynom() take an array
114       of  length  poly_ord  + 1 containing the polynomial co-efficients (a or
115       ca).
116
117       The   gd_madd_carray(),    gd_madd_const(),    gd_madd_sarray(),    and
118       gd_madd_string(), functions both add the field and set the value of the
119       field  to  value.   For  gd_madd_const()  and   gd_madd_carray(),   the
120       const_type  argument  specifies  the  storage type for the const, while
121       data_type specifies the data type of the value  pointed  to  by  value.
122       For gd_madd_sarray(), value should contain array_len string pointers.
123
124       The  gd_int64_t type is a signed 64-bit integer type.  The gd_triplet_t
125       type is defined as:
126
127           typedef union {
128             gd_int64_t i;
129             gd_uint64_t u;
130             double r;
131           } gd_triplet_t;
132
133       Which element of this gd_triplet_t union to set depends on the operator
134       selected for the WINDOW field.  See gd_entry(3) for details.
135
136       All fields added with this interface must contain numerical parameters.
137       Fields with scalar fields as parameters  cannot  be  added  with  these
138       functions.    Those   fields   must   be   added   with  gd_madd(3)  or
139       gd_madd_spec(3).  See gd_add_bit(3), &c. for an alternate way of adding
140       metafields with explicit parameters.
141
142       See   NOTES   below   for   information   on  using  gd_madd_clincom(),
143       gd_madd_cpolynom(), and gd_madd_crecip() in the C89 GetData API.
144
145

RETURN VALUE

147       On success, any of these functions returns zero.  On error, a negative-
148       valued error code is returned.  Possible error codes are:
149
150       GD_E_ACCMODE
151               The specified dirfile was opened read-only.
152
153       GD_E_ALLOC
154               The library was unable to allocate memory.
155
156       GD_E_BAD_CODE
157               The  field_name  argument  contained invalid characters. Alter‐
158               nately, the parent field code was not found, or was  already  a
159               metafield.
160
161       GD_E_BAD_DIRFILE
162               The supplied dirfile was invalid.
163
164       GD_E_BAD_ENTRY
165               One or more of the field parameters specified was invalid.
166
167       GD_E_BAD_TYPE
168               The    data_type    or    const_type   argument   provided   to
169               gd_madd_const() or gd_madd_carray() was invalid.
170
171       GD_E_DUPLICATE
172               The field_name provided duplicated that of an already  existing
173               field.
174
175       GD_E_PROTECTED
176               The metadata of the fragment was protected from change.
177
178       The  dirfile error may also be retrieved by calling gd_error(3).  A de‐
179       scriptive error string for the last error encountered can  be  obtained
180       from a call to gd_error_string(3).
181
182

NOTES

184       The    C89    GetData    API    provides   different   prototypes   for
185       gd_madd_clincom(), and gd_madd_crecip():
186
187       #define GD_C89_API
188       #include <getdata.h>
189
190       int gd_madd_clincom(DIRFILE *dirfile, const char *parent, const char
191              *field_name, int n_fields, const char **in_fields, const double
192              *cm, const double *cb);
193
194       int gd_madd_cpolynom(DIRFILE *dirfile, const char *parent, const char
195              *field_name, int poly_ord, const char *in_field, const double
196              *ca);
197
198       int gd_madd_crecip(DIRFILE *dirfile, const char *parent, const char
199              *field_name, const char *in_field, double cdividend[2], int
200              fragment_index);
201
202       In this case, the array pointers passed as cm, cb  or  ca  should  have
203       twice  as  many  (purely real) elements, consisting of alternating real
204       and imaginary parts for the complex data.  That is, for example,  ca[0]
205       should  be the real part of the first co-efficient, ca[1] the imaginary
206       part of the first co-efficient, ca[2] the real part of the  second  co-
207       efficient,  ca[3] the imaginary part of the second co-efficient, and so
208       on.  Similarly, the cdividend parameter becomes a double precision  ar‐
209       ray of length two.
210
211       For  gd_madd_clincom() and gd_madd_cpolynom(), these are simply differ‐
212       ent (but equivalent) declarations of the C99 function entry point.  For
213       gd_madd_crecip(), however, a different entry point is needed (since the
214       cdividend parameter is passed by reference instead of  by  value).   In
215       the  interests  of  portability, the C89 version of gd_madd_crecip() is
216       always available, and may be accessed as gd_madd_crecip89(),  with  the
217       C89 prototype, in both the C99 and C89 APIs.
218
219

HISTORY

221       The       functions      dirfile_madd_bit(),      dirfile_madd_const(),
222       dirfile_madd_lincom(), dirfile_madd_linterp(), dirfile_madd_multiply(),
223       dirfile_madd_phase(),  and  dirfile_madd_string()  appeared  in  GetDa‐
224       ta-0.4.0.
225
226       The    functions    dirfile_madd_clincom(),    dirfile_madd_cpolynom(),
227       dirfile_madd_polynom(),  and  dirfile_madd_sbit()  appeared  in  GetDa‐
228       ta-0.6.0.
229
230       In  GetData-0.7.0,  the  functions  were  renamed   to   gd_madd_bit(),
231       gd_madd_clincom(),         gd_madd_const(),         gd_madd_cpolynom(),
232       gd_madd_lincom(),        gd_madd_linterp(),         gd_madd_multiply(),
233       gd_madd_phase(),       gd_madd_polynom(),      gd_madd_sbit(),      and
234       gd_madd_string().  The  functions  gd_madd_carray(),  gd_madd_crecip(),
235       gd_madd_divide(), and gd_madd_recip() also appeared in this version.
236
237       In  GetData-0.8.0,  these  functions first allowed adding metafields by
238       providing the full (slashed) field name.  The functions gd_madd_mplex()
239       and gd_madd_window() also appeared in this version.
240
241       In  GetData-0.10.0,  the error return from these functions changed from
242       -1 to a negative-valued error  code.   The  functions  gd_madd_indir(),
243       gd_madd_sarray(), and gd_madd_sindir() also appeared in this version.
244
245

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

HISTORY

SEE ALSO