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