diff options
Diffstat (limited to 'funtools/man/man3/funcolumnselect.3')
| -rw-r--r-- | funtools/man/man3/funcolumnselect.3 | 664 |
1 files changed, 0 insertions, 664 deletions
diff --git a/funtools/man/man3/funcolumnselect.3 b/funtools/man/man3/funcolumnselect.3 deleted file mode 100644 index 88158c0..0000000 --- a/funtools/man/man3/funcolumnselect.3 +++ /dev/null @@ -1,664 +0,0 @@ -.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to -.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' -.\" expand to `' in nroff, nothing in troff, for use with C<>. -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ======================================================================== -.\" -.IX Title "funcolumnselect 3" -.TH funcolumnselect 3 "April 14, 2011" "version 1.4.5" "SAORD Documentation" -.SH "NAME" -FunColumnSelect \- select Funtools columns -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <funtools.h> -.Ve -.PP -.Vb 5 -\& int FunColumnSelect(Fun fun, int size, char *plist, -\& char *name1, char *type1, char *mode1, int offset1, -\& char *name2, char *type2, char *mode2, int offset2, -\& ..., -\& NULL) -.Ve -.PP -.Vb 3 -\& int FunColumnSelectArr(Fun fun, int size, char *plist, -\& char **names, char **types, char **modes, -\& int *offsets, int nargs); -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -The \fB\f(BIFunColumnSelect()\fB\fR routine is used to select the columns -from a Funtools binary table extension or raw event file for -processing. This routine allows you to specify how columns in a file -are to be read into a user record structure or written from a user -record structure to an output \s-1FITS\s0 file. -.PP -The first argument is the Fun handle associated with this set of -columns. The second argument specifies the size of the user record -structure into which columns will be read. Typically, the \fIsizeof()\fR -macro is used to specify the size of a record structure. The third -argument allows you to specify keyword directives for the selection -and is described in more detail below. -.PP -Following the first three required arguments is a variable length list of -column specifications. Each column specification will consist of four -arguments: -.IP "\(bu" 4 -\&\fBname\fR: the name of the column -.IP "\(bu" 4 -\&\fBtype\fR: the data type of the column as it will be stored in -the user record struct (not the data type of the input file). The -following basic data types are recognized: -.RS 4 -.IP "\(bu" 4 -A: \s-1ASCII\s0 characters -.IP "\(bu" 4 -B: unsigned 8-bit char -.IP "\(bu" 4 -I: signed 16-bit int -.IP "\(bu" 4 -U: unsigned 16-bit int (not standard \s-1FITS\s0) -.IP "\(bu" 4 -J: signed 32-bit int -.IP "\(bu" 4 -V: unsigned 32-bit int (not standard \s-1FITS\s0) -.IP "\(bu" 4 -E: 32-bit float -.IP "\(bu" 4 -D: 64-bit float -.RE -.RS 4 -.Sp -The syntax used is similar to that which defines the \s-1TFORM\s0 parameter -in \s-1FITS\s0 binary tables. That is, a numeric repeat value can precede -the type character, so that \*(L"10I\*(R" means a vector of 10 short ints, \*(L"E\*(R" -means a single precision float, etc. Note that the column value from -the input file will be converted to the specified data type as the -data is read by -\&\fIFunTableRowGet()\fR. -.Sp -[ A short digression regarding bit\-fields: Special attention is -required when reading or writing the \s-1FITS\s0 bit-field type -(\*(L"X\*(R"). Bit-fields almost always have a numeric repeat character -preceding the 'X' specification. Usually this value is a multiple of 8 -so that bit-fields fit into an integral number of bytes. For all -cases, the byte size of the bit-field B is (N+7)/8, where N is the -numeric repeat character. -.Sp -A bit-field is most easily declared in the user struct as an array of -type char of size B as defined above. In this case, bytes are simply -moved from the file to the user space. If, instead, a short or int -scalar or array is used, then the algorithm for reading the bit-field -into the user space depends on the size of the data type used along -with the value of the repeat character. That is, if the user data -size is equal to the byte size of the bit\-field, then the data is -simply moved (possibly with endian-based byte\-swapping) from one to -the other. If, on the other hand, the data storage is larger than the -bit-field size, then a data type cast conversion is performed to move -parts of the bit-field into elements of the array. Examples will help -make this clear: -.IP "\(bu" 4 -If the file contains a 16X bit-field and user space specifies a 2B -char array[2], then the bit-field is moved directly into the char array. -.IP "\(bu" 4 -If the file contains a 16X bit-field and user space specifies a 1I -scalar short int, then the bit-field is moved directly into the short int. -.IP "\(bu" 4 -If the file contains a 16X bit-field and user space specifies a 1J -scalar int, then the bit-field is type-cast to unsigned int before -being moved (use of unsigned avoids possible sign extension). -.IP "\(bu" 4 -If the file contains a 16X bit-field and user space specifies a 2J -int array[2], then the bit-field is handled as 2 chars, each of which -are type-cast to unsigned int before being moved (use of unsigned -avoids possible sign extension). -.IP "\(bu" 4 -If the file contains a 16X bit-field and user space specifies a 1B -char, then the bit-field is treated as a char, i.e., truncation will -occur. -.IP "\(bu" 4 -If the file contains a 16X bit-field and user space specifies a 4J -int array[4], then the results are undetermined. -.RE -.RS 4 -.Sp -For all user data types larger than char, the bit-field is byte-swapped -as necessary to convert to native format, so that bits in the -resulting data in user space can be tested, masked, etc. in the same -way regardless of platform.] -.Sp -In addition to setting data type and size, the \fBtype\fR -specification allows a few ancillary parameters to be set, using the -full syntax for \fBtype\fR: -.Sp -.Vb 1 -\& [@][n]<type>[[['B']poff]][:[tlmin[:tlmax[:binsiz]]]] -.Ve -.Sp -The special character \*(L"@\*(R" can be prepended to this specification to -indicated that the data element is a pointer in the user record, -rather than an array stored within the record. -.Sp -The [n] value is an integer that specifies the -number of elements that are in this column (default is 1). \s-1TLMIN\s0, -\&\s-1TLMAX\s0, and \s-1BINSIZ\s0 values also can be specified for this column after -the type, separated by colons. If only one such number is specified, -it is assumed to be \s-1TLMAX\s0, and \s-1TLMIN\s0 and \s-1BINSIZ\s0 are set to 1. -.Sp -The [poff] value can be used to specify the offset into an -array. By default, this offset value is set to zero and the data -specified starts at the beginning of the array. The offset usually -is specified in terms of the data type of the column. Thus an offset -specification of [5] means a 20\-byte offset if the data type is a -32-bit integer, and a 40\-byte offset for a double. If you want to -specify a byte offset instead of an offset tied to the column data type, -precede the offset value with 'B', e.g. [B6] means a 6\-bye offset, -regardless of the column data type. -.Sp -The [poff] is especially useful in conjunction with the pointer @ -specification, since it allows the data element to anywhere stored -anywhere in the allocated array. For example, a specification such as -\&\*(L"@I[2]\*(R" specifies the third (i.e., starting from 0) element in the -array pointed to by the pointer value. A value of \*(L"@2I[4]\*(R" specifies -the fifth and sixth values in the array. For example, consider the -following specification: -.Sp -.Vb 12 -\& typedef struct EvStruct{ -\& short x[4], *atp; -\& } *Event, EventRec; -\& /* set up the (hardwired) columns */ -\& FunColumnSelect( fun, sizeof(EventRec), NULL, -\& "2i", "2I ", "w", FUN_OFFSET(Event, x), -\& "2i2", "2I[2]", "w", FUN_OFFSET(Event, x), -\& "at2p", "@2I", "w", FUN_OFFSET(Event, atp), -\& "at2p4", "@2I[4]", "w", FUN_OFFSET(Event, atp), -\& "atp9", "@I[9]", "w", FUN_OFFSET(Event, atp), -\& "atb20", "@I[B20]", "w", FUN_OFFSET(Event, atb), -\& NULL); -.Ve -.Sp -Here we have specified the following columns: -.IP "\(bu" 4 -2i: two short ints in an array which is stored as part the -record -.IP "\(bu" 4 -2i2: the 3rd and 4th elements of an array which is stored -as part of the record -.IP "\(bu" 4 -an array of at least 10 elements, not stored in the record but -allocated elsewhere, and used by three different columns: -.RS 4 -.IP "\(bu" 4 -at2p: 2 short ints which are the first 2 elements of the allocated array -.IP "\(bu" 4 -at2p4: 2 short ints which are the 5th and 6th elements of -the allocated array -.IP "\(bu" 4 -atp9: a short int which is the 10th element of the allocated array -.RE -.RS 4 -.RE -.IP "\(bu" 4 -atb20: a short int which is at byte offset 20 of another allocated array -.RE -.RS 4 -.Sp -In this way, several columns can be specified, all of which are in a -single array. \fB\s-1NB\s0\fR: it is the programmer's responsibility to -ensure that specification of a positive value for poff does not point -past the end of valid data. -.RE -.IP "\(bu" 4 -\&\fBread/write mode\fR: \*(L"r\*(R" means that the column is read from an -input file into user space by -\&\fIFunTableRowGet()\fR, \*(L"w\*(R" means that -the column is written to an output file. Both can specified at the same -time. -.IP "\(bu" 4 -\&\fBoffset\fR: the offset into the user data to store -this column. Typically, the macro \s-1FUN_OFFSET\s0(recname, colname) is used -to define the offset into a record structure. -.PP -When all column arguments have been specified, a final \s-1NULL\s0 argument -must added to signal the column selection list. -.PP -As an alternative to the varargs -\&\fIFunColumnSelect()\fR -routine, a non-varargs routine called -\&\fIFunColumnSelectArr()\fR -also is available. The first three arguments (fun, size, plist) of this -routine are the same as in -\&\fIFunColumnSelect()\fR. -Instead of a variable -argument list, however, -\&\fIFunColumnSelectArr()\fR -takes 5 additional arguments. The first 4 arrays arguments contain the -names, types, modes, and offsets, respectively, of the columns being -selected. The final argument is the number of columns that are -contained in these arrays. It is the user's responsibility to free -string space allocated in these arrays. -.PP -Consider the following example: -.PP -.Vb 5 -\& typedef struct evstruct{ -\& int status; -\& float pi, pha, *phas; -\& double energy; -\& } *Ev, EvRec; -.Ve -.PP -.Vb 6 -\& FunColumnSelect(fun, sizeof(EvRec), NULL, -\& "status", "J", "r", FUN_OFFSET(Ev, status), -\& "pi", "E", "r", FUN_OFFSET(Ev, pi), -\& "pha", "E", "r", FUN_OFFSET(Ev, pha), -\& "phas", "@9E", "r", FUN_OFFSET(Ev, phas), -\& NULL); -.Ve -.PP -Each time a row is read into the Ev struct, the \*(L"status\*(R" column is -converted to an int data type (regardless of its data type in the -file) and stored in the status value of the struct. Similarly, \*(L"pi\*(R" -and \*(L"pha\*(R", and the phas vector are all stored as floats. Note that the -\&\*(L"@\*(R" sign indicates that the \*(L"phas\*(R" vector is a pointer to a 9 element -array, rather than an array allocated in the struct itself. The row -record can then be processed as required: -.PP -.Vb 9 -\& /* get rows -- let routine allocate the row array */ -\& while( (ebuf = (Ev)FunTableRowGet(fun, NULL, MAXROW, NULL, &got)) ){ -\& /* process all rows */ -\& for(i=0; i<got; i++){ -\& /* point to the i'th row */ -\& ev = ebuf+i; -\& ev->pi = (ev->pi+.5); -\& ev->pha = (ev->pi-.5); -\& } -.Ve -.PP -\&\fIFunColumnSelect()\fR -can also be called to define \*(L"writable\*(R" columns in order to generate a \s-1FITS\s0 -Binary Table, without reference to any input columns. For -example, the following will generate a 4\-column \s-1FITS\s0 binary table when -\&\fIFunTableRowPut()\fR is used to -write Ev records: -.PP -.Vb 5 -\& typedef struct evstruct{ -\& int status; -\& float pi, pha -\& double energy; -\& } *Ev, EvRec; -.Ve -.PP -.Vb 6 -\& FunColumnSelect(fun, sizeof(EvRec), NULL, -\& "status", "J", "w", FUN_OFFSET(Ev, status), -\& "pi", "E", "w", FUN_OFFSET(Ev, pi), -\& "pha", "E", "w", FUN_OFFSET(Ev, pha), -\& "energy", "D", "w", FUN_OFFSET(Ev, energy), -\& NULL); -.Ve -.PP -All columns are declared to be write\-only, so presumably the column -data is being generated or read from some other source. -.PP -In addition, -\&\fIFunColumnSelect()\fR -can be called to define \fBboth\fR \*(L"readable\*(R" and \*(L"writable\*(R" columns. -In this case, the \*(L"read\*(R" columns -are associated with an input file, while the \*(L"write\*(R" columns are -associated with the output file. Of course, columns can be specified as both -\&\*(L"readable\*(R" and \*(L"writable\*(R", in which case they are read from input -and (possibly modified data values are) written to the output. -The -\&\fIFunColumnSelect()\fR -call itself is made by passing the input Funtools handle, and it is -assumed that the output file has been opened using this input handle -as its -Funtools reference handle. -.PP -Consider the following example: -.PP -.Vb 5 -\& typedef struct evstruct{ -\& int status; -\& float pi, pha, *phas; -\& double energy; -\& } *Ev, EvRec; -.Ve -.PP -.Vb 7 -\& FunColumnSelect(fun, sizeof(EvRec), NULL, -\& "status", "J", "r", FUN_OFFSET(Ev, status), -\& "pi", "E", "rw", FUN_OFFSET(Ev, pi), -\& "pha", "E", "rw", FUN_OFFSET(Ev, pha), -\& "phas", "@9E", "rw", FUN_OFFSET(Ev, phas), -\& "energy", "D", "w", FUN_OFFSET(Ev, energy), -\& NULL); -.Ve -.PP -As in the \*(L"read\*(R" example above, each time an row is read into the Ev -struct, the \*(L"status\*(R" column is converted to an int data type -(regardless of its data type in the file) and stored in the status -value of the struct. Similarly, \*(L"pi\*(R" and \*(L"pha\*(R", and the phas vector -are all stored as floats. Since the \*(L"pi\*(R", \*(L"pha\*(R", and \*(L"phas\*(R" variables -are declared as \*(L"writable\*(R" as well as \*(L"readable\*(R", they also will be -written to the output file. Note, however, that the \*(L"status\*(R" variable -is declared as \*(L"readable\*(R" only, and hence it will not be written to -an output file. Finally, the \*(L"energy\*(R" column is declared as -\&\*(L"writable\*(R" only, meaning it will not be read from the input file. In -this case, it can be assumed that \*(L"energy\*(R" will be calculated in the -program before being output along with the other values. -.PP -In these simple cases, only the columns specified as \*(L"writable\*(R" will -be output using -\&\fIFunTableRowPut()\fR. However, -it often is the case that you want to merge the user columns back in -with the input columns, even in cases where not all of the input -column names are explicitly read or even known. For this important -case, the \fBmerge=[type]\fR keyword is provided in the plist string. -.PP -The \fBmerge=[type]\fR keyword tells Funtools to merge the columns from -the input file with user columns on output. It is normally used when -an input and output file are opened and the input file provides the -Funtools reference handle -for the output file. In this case, each time -\&\fIFunTableRowGet()\fR is called, the -raw input rows are saved in a special buffer. If -\&\fIFunTableRowPut()\fR then is called -(before another call to -\&\fIFunTableRowGet()\fR), the contents -of the raw input rows are merged with the user rows according to the -value of \fBtype\fR as follows: -.IP "\(bu" 4 -\&\fBupdate\fR: add new user columns, and update value of existing ones (maintaining the input data type) -.IP "\(bu" 4 -\&\fBreplace\fR: add new user columns, and replace the data type -and value of existing ones. (Note that if tlmin/tlmax values are not -specified in the replacing column, but are specified in the original -column being replaced, then the original tlmin/tlmax values are used -in the replacing column.) -.IP "\(bu" 4 -\&\fBappend\fR: only add new columns, do not \*(L"replace\*(R" or \*(L"update\*(R" existing ones -.PP -Consider the example above. If \fBmerge=update\fR is specified in the -plist string, then \*(L"energy\*(R" will be added to the input columns, and -the values of \*(L"pi\*(R", \*(L"pha\*(R", and \*(L"phas\*(R" will be taken from the user -space (i.e., the values will be updated from the original values, if -they were changed by the program). The data type for \*(L"pi\*(R", \*(L"pha\*(R", and -\&\*(L"phas\*(R" will be the same as in the original file. If -\&\fBmerge=replace\fR is specified, both the data type and value of -these three input columns will be changed to the data type and value -in the user structure. If \fBmerge=append\fR is specified, none of -these three columns will be updated, and only the \*(L"energy\*(R" column will -be added. Note that in all cases, \*(L"status\*(R" will be written from the -input data, not from the user record, since it was specified as read\-only. -.PP -Standard applications will call -\&\fIFunColumnSelect()\fR -to define user columns. However, if this routine is not called, the -default behavior is to transfer all input columns into user space. For -this purpose a default record structure is defined such that each data -element is properly aligned on a valid data type boundary. This -mechanism is used by programs such as fundisp and funtable to process -columns without needing to know the specific names of those columns. -It is not anticipated that users will need such capabilities (contact -us if you do!) -.PP -By default, \fIFunColumnSelect()\fR -reads/writes rows to/from an \*(L"array of structs\*(R", where each struct contains -the column values for a single row of the table. This means that the -returned values for a given column are not contiguous. You can -set up the \s-1IO\s0 to return a \*(L"struct of arrays\*(R" so that each of the -returned columns are contiguous by specifying \fBorg=structofarrays\fR -(abbreviation: \fBorg=soa\fR) in the plist. -(The default case is \fBorg=arrayofstructs\fR or \fBorg=aos\fR.) -.PP -For example, the default setup to retrieve rows from a table would be -to define a record structure for a single event and then call - \fIFunColumnSelect()\fR -as follows: -.PP -.Vb 6 -\& typedef struct evstruct{ -\& short region; -\& double x, y; -\& int pi, pha; -\& double time; -\& } *Ev, EvRec; -.Ve -.PP -.Vb 7 -\& got = FunColumnSelect(fun, sizeof(EvRec), NULL, -\& "x", "D:10:10", mode, FUN_OFFSET(Ev, x), -\& "y", "D:10:10", mode, FUN_OFFSET(Ev, y), -\& "pi", "J", mode, FUN_OFFSET(Ev, pi), -\& "pha", "J", mode, FUN_OFFSET(Ev, pha), -\& "time", "1D", mode, FUN_OFFSET(Ev, time), -\& NULL); -.Ve -.PP -Subsequently, each call to -\&\fIFunTableRowGet()\fR -will return an array of structs, one for each returned row. If instead you -wanted to read columns into contiguous arrays, you specify \fBorg=soa\fR: -.PP -.Vb 6 -\& typedef struct aevstruct{ -\& short region[MAXROW]; -\& double x[MAXROW], y[MAXROW]; -\& int pi[MAXROW], pha[MAXROW]; -\& double time[MAXROW]; -\& } *AEv, AEvRec; -.Ve -.PP -.Vb 7 -\& got = FunColumnSelect(fun, sizeof(AEvRec), "org=soa", -\& "x", "D:10:10", mode, FUN_OFFSET(AEv, x), -\& "y", "D:10:10", mode, FUN_OFFSET(AEv, y), -\& "pi", "J", mode, FUN_OFFSET(AEv, pi), -\& "pha", "J", mode, FUN_OFFSET(AEv, pha), -\& "time", "1D", mode, FUN_OFFSET(AEv, time), -\& NULL); -.Ve -.PP -Note that the only modification to the call is in the plist string. -.PP -Of course, instead of using statically allocated arrays, you also can specify -dynamically allocated pointers: -.PP -.Vb 7 -\& /* pointers to arrays of columns (used in struct of arrays) */ -\& typedef struct pevstruct{ -\& short *region; -\& double *x, *y; -\& int *pi, *pha; -\& double *time; -\& } *PEv, PEvRec; -.Ve -.PP -.Vb 8 -\& got = FunColumnSelect(fun, sizeof(PEvRec), "org=structofarrays", -\& "$region", "@I", mode, FUN_OFFSET(PEv, region), -\& "x", "@D:10:10", mode, FUN_OFFSET(PEv, x), -\& "y", "@D:10:10", mode, FUN_OFFSET(PEv, y), -\& "pi", "@J", mode, FUN_OFFSET(PEv, pi), -\& "pha", "@J", mode, FUN_OFFSET(PEv, pha), -\& "time", "@1D", mode, FUN_OFFSET(PEv, time), -\& NULL); -.Ve -.PP -Here, the actual storage space is either allocated by the user or by the -\&\fIFunColumnSelect()\fR call). -.PP -In all of the above cases, the same call is made to retrieve rows, e.g.: -.PP -.Vb 1 -\& buf = (void *)FunTableRowGet(fun, NULL, MAXROW, NULL, &got); -.Ve -.PP -However, the individual data elements are accessed differently. -For the default case of an \*(L"array of structs\*(R", the -individual row records are accessed using: -.PP -.Vb 5 -\& for(i=0; i<got; i++){ -\& ev = (Ev)buf+i; -\& fprintf(stdout, "%.2f\et%.2f\et%d\et%d\et%.4f\et%.4f\et%21.8f\en", -\& ev->x, ev->y, ev->pi, ev->pha, ev->dx, ev->dy, ev->time); -\& } -.Ve -.PP -For a struct of arrays or a struct of array pointers, we have a single struct -through which we access individual columns and rows using: -.PP -.Vb 6 -\& aev = (AEv)buf; -\& for(i=0; i<got; i++){ -\& fprintf(stdout, "%.2f\et%.2f\et%d\et%d\et%.4f\et%.4f\et%21.8f\en", -\& aev->x[i], aev->y[i], aev->pi[i], aev->pha[i], -\& aev->dx[i], aev->dy[i], aev->time[i]); -\& } -.Ve -.PP -Support for struct of arrays in the -\&\fIFunTableRowPut()\fR -call is handled analogously. -.PP -See the evread example code -and -evmerge example code -for working examples of how -\&\fIFunColumnSelect()\fR is used. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -See funtools(7) for a list of Funtools help pages |