diff options
Diffstat (limited to 'funtools/doc/pod/funtablerowget.pod')
-rw-r--r-- | funtools/doc/pod/funtablerowget.pod | 111 |
1 files changed, 111 insertions, 0 deletions
diff --git a/funtools/doc/pod/funtablerowget.pod b/funtools/doc/pod/funtablerowget.pod new file mode 100644 index 0000000..86c1e66 --- /dev/null +++ b/funtools/doc/pod/funtablerowget.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + + + +B<FunTableRowGet - get Funtools rows> + + + +=head1 SYNOPSIS + + + + + + #include <funtools.h> + + void *FunTableRowGet(Fun fun, void *rows, int maxrow, char *plist, + int *nrow) + + + + + +=head1 DESCRIPTION + + + + +The B<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 B<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 B<maxrow> argument specifies the maximum number +of rows to be returned. Thus, if B<rows> is allocated by the +user, it should be at least of size maxrow*sizeof(evstruct). + + +The fourth B<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. + + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + +=cut |