NAME¶
FunTableRowGet - get Funtools rows
SYNOPSIS¶
#include <funtools.h>
void *FunTableRowGet(Fun fun, void *rows, int maxrow, char *plist,
int *nrow)
DESCRIPTION¶
The
FunTableRowGet() routine retrieves rows from a
Funtools binary table or raw event file, and places the values of columns
selected by
FunColumnSelect() into an array of user structs. Selected
column values are automatically converted to the specified user data type (and
to native data format) as necessary.
The first argument is the Fun handle associated with this row data. The second
rows argument is the array of user structs into which the selected
columns will be stored. If NULL is passed, the routine will automatically
allocate space for this array. (This includes proper allocation of pointers
within each struct, if the "@" pointer type is used in the selection
of columns. Note that if you pass NULL in the second argument, you should free
this space using the standard
free() system call when you are finished
with the array of rows.) The third
maxrow argument specifies the
maximum number of rows to be returned. Thus, if
rows is allocated by
the user, it should be at least of size maxrow*sizeof(evstruct).
The fourth
plist argument is a param list string. Currently, the
keyword/value pair "mask=transparent" is supported in the plist
argument. If this string is passed in the call's plist argument, then all rows
are passed back to the user (instead of just rows passing the filter). This is
only useful when
FunColumnSelect() also is used to specify
"$region" as a column to return for each row. In such a case, rows
found within a region have a returned region value greater than 0
(corresponding to the region id of the region in which they are located), rows
passing the filter but not in a region have region value of \-1, and rows not
passing any filter have region value of 0. Thus, using
"mask=transparent" and the returned region value, a program can
process all rows and decide on an action based on whether a given row passed
the filter or not.
The final argument is a pointer to an int variable that will return the actual
number of rows returned. The routine returns a pointer to the array of stored
rows, or NULL if there was an error. (This pointer will be the same as the
second argument, if the latter is non\-NULL).
/* 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;
/* rearrange some values. etc. */
ev->energy = (ev->pi+ev->pha)/2.0;
ev->pha = -ev->pha;
ev->pi = -ev->pi;
}
/* write out this batch of rows */
FunTableRowPut(fun2, buf, got, 0, NULL);
/* free row data */
if( buf ) free(buf);
}
As shown above, successive calls to
FunTableRowGet() will return the next
set of rows from the input file until all rows have been read, i.e., the
routine behaves like sequential Unix I/O calls such as
fread(). See
evmerge example code for a more complete example.
Note that
FunTableRowGet() also can be called as
FunEventsGet(),
for backward compatibility.
SEE ALSO¶
See
funtools(7) for a list of Funtools help pages