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