=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
