1funtablerowput(3)             SAORD Documentation            funtablerowput(3)
2
3
4

NAME

6       FunTableRowPut - put Funtools rows
7

SYNOPSIS

9       int FunTableRowPut(Fun fun, void *rows, int nev, int idx, char *plist)
10

DESCRIPTION

12       The FunTableRowPut() routine writes rows to a FITS binary table, taking
13       its input from an array of user structs that contain column values
14       selected by a previous call to FunColumnSelect().  Selected column val‐
15       ues are automatically converted from native data format to FITS data
16       format as necessary.
17
18       The first argument is the Fun handle associated with this row data.
19       The second rows argument is the array of user structs to output. The
20       third nrow argument specifies the number number of rows to write.  The
21       routine will write nrow records, starting from the location specified
22       by rows.
23
24       The fourth idx argument is the index of the first raw input row to
25       write, in the case where rows from the user buffer are being merged
26       with their raw input row counterparts (see below). Note that this idx
27       value is has nothing to do with the row buffer specified in argument 1.
28       It merely matches the row being written with its corresponding (hidden)
29       raw row.  Thus, if you read a number of rows, process them, and then
30       write them out all at once starting from the first user row, the value
31       of idx should be 0:
32
33         Ev ebuf, ev;
34         /* get rows -- let routine allocate the row array */
35         while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
36           /* process all rows */
37           for(i=0; i<got; i++){
38             /* point to the i'th row */
39             ev = ebuf+i;
40             ...
41           }
42           /* write out this batch of rows, starting with the first */
43           FunTableRowPut(fun2, (char *)ebuf, got, 0, NULL);
44           /* free row data */
45           if( ebuf ) free(ebuf);
46         }
47
48       On the other hand, if you write out the rows one at a time (possibly
49       skipping rows), then, when writing the i'th row from the input array of
50       rows, set idx to the value of i:
51
52         Ev ebuf, ev;
53         /* get rows -- let routine allocate the row array */
54         while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
55           /* process all rows */
56           for(i=0; i<got; i++){
57             /* point to the i'th row */
58             ev = ebuf+i;
59             ...
60             /* write out the current (i.e., i'th) row */
61             FunTableRowPut(fun2, (char *)ev, 1, i, NULL);
62           }
63           /* free row data */
64           if( ebuf ) free(ebuf);
65         }
66
67       The final argument is a param list string that is not currently used.
68       The routine returns the number of rows output.  This should be equal to
69       the value passed in the third nrow</B argument.
70
71       When FunTableRowPut() is first called for a given binary table, Fun‐
72       tools checks to see of the primary header has already been written
73       (either by writing a previous row table or by writing an image.) If
74       not, a dummy primary header is written to the file specifying that an
75       extension should be expected.  After this, a binary table header is
76       automatically written containing information about the columns that
77       will populate this table.  In addition, if a Funtools reference handle
78       was specified when this table was opened, the parameters from this Fun‐
79       tools reference handle are merged into the new binary table header.
80
81       In a typical Funtools row loop, you read rows using FunTableRowGet()()
82       and write rows using FunTableRowPut(). The columns written by FunT‐
83       ableRowPut()() are those defined as writable by a previous call to Fun‐
84       ColumnSelect().  If that call to FunColumnSelect also specified
85       merge=[update⎪replace⎪append], then the entire corresponding raw input
86       row record will be merged with the output row according to the merge
87       specification (see FunColumnSelect() above).
88
89       A call to write rows can either be done once, after all rows in the
90       input batch have been processed, or it can be done (slightly less effi‐
91       ciently) one row at a time (or anything in between). We do recommend
92       that you write all rows associated with a given batch of input rows
93       before reading new rows.  This is required if you are merging the out‐
94       put rows with the raw input rows (since the raw rows are destroyed with
95       each successive call to get new rows).
96
97       For example:
98
99         Ev buf, ev;
100         ...
101         /* get rows -- let routine allocate the row array */
102         while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
103           /* point to the i'th row */
104           ev = buf + i;
105           .... process
106         }
107         /* write out this batch of rows */
108         FunTableRowPut(fun2, buf, got, 0, NULL);
109         /* free row data */
110         if( buf ) free(buf);
111         }
112
113       or
114
115         Ev buf, ev;
116         ...
117         /* get rows -- let routine allocate the row array */
118         while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
119           /* process all rows */
120           for(i=0; i<got; i++){
121             /* point to the i'th row */
122             ev = buf + i;
123             ... process
124             /* write out this batch of rows with the new column */
125             if( dowrite )
126               FunTableRowPut(fun2, buf, 1, i, NULL);
127           }
128           /* free row data */
129           if( buf ) free(buf);
130         }
131
132       Note that the difference between these calls is that the first one out‐
133       puts got rows all at once and therefore passes idx=0 in argument four,
134       so that merging starts at the first raw input row.  In the second case,
135       a check it made on each row to see if it needs to be output.  If so,
136       the value of idx is passed as the value of the i variable which points
137       to the current row being processed in the batch of input rows.
138
139       As shown above, successive calls to FunTableRowPut() will write rows
140       sequentially. When you are finished writing all rows in a table, you
141       should call FunFlush() to write out the FITS binary table padding. How‐
142       ever, this is not necessary if you subsequently call FunClose() without
143       doing any other I/O to the FITS file.
144
145       Note that FunTableRowPut() also can be called as FunEventsPut(), for
146       backward compatibility.
147

SEE ALSO

149       See funtools(n) for a list of Funtools help pages
150
151
152
153version 1.4.2                   January 2, 2008              funtablerowput(3)
Impressum