1 files changed, 180 insertions, 0 deletions
diff --git a/doc/pod/funinfoput.pod b/doc/pod/funinfoput.pod
new file mode 100644
index 0000000..5124dfc
--- /dev/null
+++ b/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