1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
|
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.\"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "funtablerowput 3"
.TH funtablerowput 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation"
.SH "NAME"
FunTableRowPut \- put Funtools rows
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
int FunTableRowPut(Fun fun, void *rows, int nev, int idx, char *plist)
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fB\f(BIFunTableRowPut()\fB\fR routine writes rows to a \s-1FITS\s0 binary
table, taking its input from an array of user structs that contain
column values selected by a previous call to
\&\fIFunColumnSelect()\fR. Selected
column values are automatically converted from native data format to
\&\s-1FITS\s0 data format as necessary.
.PP
The first argument is the Fun handle associated with this row data.
The second \fBrows\fR argument is the array of user structs to
output. The third \fBnrow\fR argument specifies the number number of
rows to write. The routine will write \fBnrow\fR records, starting
from the location specified by \fBrows\fR.
.PP
The fourth \fBidx\fR argument is the index of the first raw input
row to write, in the case where rows from the user buffer are
being merged with their raw input row counterparts (see below). Note
that this \fBidx\fR value is has nothing to do with the
row buffer specified in argument 1. It merely matches the row
being written with its corresponding (hidden) raw row. Thus, if you
read a number of rows, process them, and then write them out all at
once starting from the first user row, the value of \fBidx\fR
should be 0:
.PP
.Vb 14
\& Ev ebuf, ev;
\& /* get rows -- let routine allocate the row array */
\& while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
\& /* process all rows */
\& for(i=0; i<got; i++){
\& /* point to the i'th row */
\& ev = ebuf+i;
\& ...
\& }
\& /* write out this batch of rows, starting with the first */
\& FunTableRowPut(fun2, (char *)ebuf, got, 0, NULL);
\& /* free row data */
\& if( ebuf ) free(ebuf);
\& }
.Ve
.PP
On the other hand, if you write out the rows one at a time (possibly
skipping rows), then, when writing the i'th row from the input
array of rows, set \fBidx\fR to the value of i:
.PP
.Vb 14
\& Ev ebuf, ev;
\& /* get rows -- let routine allocate the row array */
\& while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
\& /* process all rows */
\& for(i=0; i<got; i++){
\& /* point to the i'th row */
\& ev = ebuf+i;
\& ...
\& /* write out the current (i.e., i'th) row */
\& FunTableRowPut(fun2, (char *)ev, 1, i, NULL);
\& }
\& /* free row data */
\& if( ebuf ) free(ebuf);
\& }
.Ve
.PP
The final argument is a param list string that is not currently used.
The routine returns the number of rows output. This should be equal
to the value passed in the third nrow</B argument.
.PP
When \fIFunTableRowPut()\fR is first
called for a given binary table, Funtools checks to see of the primary
header has already been written (either by writing a previous row
table or by writing an image.) If not, a dummy primary header is
written to the file specifying that an extension should be expected.
After this, a binary table header is automatically written containing
information about the columns that will populate this table. In
addition, if a
Funtools reference handle
was specified when this table was opened, the parameters from this
Funtools reference handle
are merged into the new binary table header.
.PP
In a typical Funtools row loop, you read rows using
\&\fIFunTableRowGet()\fR() and write
rows using \fIFunTableRowPut()\fR. The columns written by
\&\fIFunTableRowPut()\fR() are those defined as writable by a previous call to
\&\fIFunColumnSelect()\fR. If
that call to FunColumnSelect also specified
\&\fBmerge=[update|replace|append]\fR, then the entire corresponding
raw input row record will be merged with the output row according
to the \fBmerge\fR specification (see
\&\fIFunColumnSelect()\fR above).
.PP
A call to write rows can either be done once, after all rows in
the input batch have been processed, or it can be done (slightly less
efficiently) one row at a time (or anything in between). We do
recommend that you write all rows associated with a given batch of
input rows before reading new rows. This is \fBrequired\fR if
you are merging the output rows with the raw input rows (since
the raw rows are destroyed with each successive call to get new rows).
.PP
For example:
.PP
.Vb 13
\& Ev buf, ev;
\& ...
\& /* get rows -- let routine allocate the row array */
\& while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
\& /* point to the i'th row */
\& ev = buf + i;
\& .... process
\& }
\& /* write out this batch of rows */
\& FunTableRowPut(fun2, buf, got, 0, NULL);
\& /* free row data */
\& if( buf ) free(buf);
\& }
.Ve
.PP
or
.PP
.Vb 16
\& Ev buf, ev;
\& ...
\& /* get rows -- let routine allocate the row array */
\& while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
\& /* process all rows */
\& for(i=0; i<got; i++){
\& /* point to the i'th row */
\& ev = buf + i;
\& ... process
\& /* write out this batch of rows with the new column */
\& if( dowrite )
\& FunTableRowPut(fun2, buf, 1, i, NULL);
\& }
\& /* free row data */
\& if( buf ) free(buf);
\& }
.Ve
.PP
Note that the difference between these calls is that the first one
outputs \fBgot\fR rows all at once and therefore passes
\&\fBidx=0\fR in argument four, so that merging starts at the first raw
input row. In the second case, a check it made on each row to see
if it needs to be output. If so, the value of \fBidx\fR is passed as
the value of the \fBi\fR variable which points to the current row
being processed in the batch of input rows.
.PP
As shown above, successive calls to
\&\fIFunTableRowPut()\fR will write
rows sequentially. When you are finished writing all rows in a
table, you should call
\&\fIFunFlush()\fR to write out the \s-1FITS\s0
binary table padding. However, this is not necessary if you
subsequently call \fIFunClose()\fR without doing any other I/O to the \s-1FITS\s0
file.
.PP
Note that \fIFunTableRowPut()\fR also can be called as \fIFunEventsPut()\fR, for
backward compatibility.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See funtools(7) for a list of Funtools help pages
|