diff options
Diffstat (limited to 'funtools/doc/pod/funinfoput.pod')
-rw-r--r-- | funtools/doc/pod/funinfoput.pod | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/funtools/doc/pod/funinfoput.pod b/funtools/doc/pod/funinfoput.pod new file mode 100644 index 0000000..5124dfc --- /dev/null +++ b/funtools/doc/pod/funinfoput.pod @@ -0,0 +1,180 @@ +=pod + +=head1 NAME + + + +B<FunInfoPut - put information into a Funtools struct> + + + +=head1 SYNOPSIS + + + + + + #include <funtools.h> + + int FunInfoPut(Fun fun, int type, char *addr, ...) + + + + + +=head1 DESCRIPTION + + + + +The B<FunInfoPut()> routine puts information into a Funtools +structure. The first argument is the Fun handle from which +information is to be retrieved. After this first required argument +comes a variable length list of pairs of arguments. Each pair consists +of an integer representing the type of information to store and the +address of the new information to store in the struct. The variable +list is terminated by a 0. The routine returns the number of put +actions performed. + + +The full list of available information is described above with the +FunInfoPut() routine. Although +use of this routine is expected to be uncommon, there is one +important situation in which it plays an essential part: writing +multiple extensions to a single output file. + + +For input, multiple extensions are handled by calling +FunOpen() for each extension to be +processed. When opening multiple inputs, it sometimes is the case that +you will want to process them and then write them (including their +header parameters) to a single output file. To accomplish this, you +open successive input extensions using +FunOpen() and then call +B<FunInfoPut()> to set the +Funtools reference handle +of the output file to that of the newly opened input extension: + + /* open a new input extension */ + ifun=FunOpen(tbuf, "r", NULL)) ) + /* make the new extension the reference handle for the output file */ + FunInfoPut(ofun, FUN_IFUN, &ifun, 0); + + +Resetting FUN_IFUN has same effect as when a funtools handle is passed +as the final argument to +FunOpen(). The state of the output +file is reset so that a new extension is ready to be written. +Thus, the next I/O call on the output extension will output the +header, as expected. + + +For example, in a binary table, after resetting FUN_IFUN you can then +call FunColumnSelect() to +select the columns for output. When you then call +FunImagePut() or <A +HREF="./library.html#funtablerowput">FunTableRowPut(), a new +extension will be written that contains the header parameters from the +reference extension. Remember to call +FunFlush() to complete output of a +given extension. + + +A complete example of this capability is given +in the evcol example code. +The central algorithm is: + + +=over 4 + + + + +=item * + +open the output file without a reference handle + + +=item * + +loop: open each input extension in turn + + +=over 4 + + + + +=item * + +set the reference handle for output to the newly opened input extension + + +=item * + +read the input rows or image and perform processing + + +=item * + +write new rows or image to the output file + + +=item * + +flush the output + + +=item * + +close input extension + + +=back + + + + +=item * + +close output file + + +=back + + +Note that FunFlush() is called +after processing each input extension in order to ensure that the +proper padding is written to the output file. A call to +FunFlush() also ensures that the +extension header is written to the output file in the case where there +are no rows to output. + + +If you wish to output a new extension without using a +Funtools reference handle, you can +call FunInfoPut() to reset the FUN_OPS value directly. For a binary +table, you would then call FunColumnSelect() to set up the columns for +this new extension. + + /* reset the operations performed on this handle */ + int ops=0; + FunInfoPut(ofun, FUN_OPS, &ops, 0); + FunColumnSelect(fun, sizeof(EvRec), NULL, + "MYCOL", "J", "w", FUN_OFFSET(Ev, mycol), + NULL); + +Once the FUN_OPS variable has been reset, the next I/O call on the +output extension will output the header, as expected. + + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + +=cut |