funtablerowget(3)

1funtablerowget(3)             SAORD Documentation            funtablerowget(3)
2
3
4

NAME

6       FunTableRowGet - get Funtools rows
7

SYNOPSIS

9         #include <funtools.h>
10
11         void *FunTableRowGet(Fun fun, void *rows, int maxrow, char *plist,
12                              int *nrow)
13

DESCRIPTION

15       The FunTableRowGet() routine retrieves rows from a Funtools binary ta‐
16       ble or raw event file, and places the values of columns selected by
17       FunColumnSelect() into an array of user structs.  Selected column val‐
18       ues are automatically converted to the specified user data type (and to
19       native data format) as necessary.
20
21       The first argument is the Fun handle associated with this row data.
22       The second rows argument is the array of user structs into which the
23       selected columns will be stored. If NULL is passed, the routine will
24       automatically allocate space for this array. (This includes proper
25       allocation of pointers within each struct, if the "@" pointer type is
26       used in the selection of columns.  Note that if you pass NULL in the
27       second argument, you should free this space using the standard free()
28       system call when you are finished with the array of rows.)  The third
29       maxrow argument specifies the maximum number of rows to be returned.
30       Thus, if rows is allocated by the user, it should be at least of size
31       maxrow*sizeof(evstruct).
32
33       The fourth plist argument is a param list string.  Currently, the key‐
34       word/value pair "mask=transparent" is supported in the plist argument.
35       If this string is passed in the call's plist argument, then all rows
36       are passed back to the user (instead of just rows passing the filter).
37       This is only useful when FunColumnSelect() also is used to specify
38       "$region" as a column to return for each row.  In such a case, rows
39       found within a region have a returned region value greater than 0 (cor‐
40       responding to the region id of the region in which they are located),
41       rows passing the filter but not in a region have region value of -1,
42       and rows not passing any filter have region value of 0. Thus, using
43       "mask=transparent" and the returned region value, a program can process
44       all rows and decide on an action based on whether a given row passed
45       the filter or not.
46
47       The final argument is a pointer to an int variable that will return the
48       actual number of rows returned.  The routine returns a pointer to the
49       array of stored rows, or NULL if there was an error. (This pointer will
50       be the same as the second argument, if the latter is non-NULL).
51
52         /* get rows -- let routine allocate the row array */
53         while( (buf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){
54           /* process all rows */
55           for(i=0; i<got; i++){
56             /* point to the i'th row */
57             ev = buf+i;
58             /* rearrange some values. etc. */
59             ev->energy = (ev->pi+ev->pha)/2.0;
60             ev->pha = -ev->pha;
61             ev->pi = -ev->pi;
62           }
63           /* write out this batch of rows */
64           FunTableRowPut(fun2, buf, got, 0, NULL);
65           /* free row data */
66           if( buf ) free(buf);
67         }
68
69       As shown above, successive calls to FunTableRowGet() will return the
70       next set of rows from the input file until all rows have been read,
71       i.e., the routine behaves like sequential Unix I/O calls such as
72       fread(). See evmerge example code for a more complete example.
73
74       Note that FunTableRowGet() also can be called as FunEventsGet(), for
75       backward compatibility.
76

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO