1 files changed, 166 insertions, 0 deletions
diff --git a/funtools/doc/pod/funopen.pod b/funtools/doc/pod/funopen.pod
new file mode 100644
index 0000000..3d6ab3e
--- /dev/null
+++ b/funtools/doc/pod/funopen.pod
@@ -0,0 +1,166 @@
+=pod
+
+=head1 NAME
+
+
+
+B<FunOpen - open a Funtools data file>
+
+
+
+=head1 SYNOPSIS
+
+
+
+
+
+  #include <funtools.h>
+
+  Fun FunOpen(char *name, char *mode, Fun ref);
+
+
+
+
+
+=head1 DESCRIPTION
+
+
+
+
+The B<FunOpen()> routine opens a Funtools data file for reading or
+appending, or creates a new FITS file for writing. The B<name>
+argument specifies the name of the Funtools data file to open. You can
+use IRAF-style bracket notation to specify
+Funtools Files, Extensions, and Filters.
+A separate call should be made each time a different FITS extension is
+accessed:
+
+  Fun fun;
+  char *iname;
+  ...
+  if( !(fun = FunOpen(iname, "r", NULL)) ){
+    fprintf(stderr, "could not FunOpen input file: %s\n", iname);
+    exit(1);
+  }
+
+
+If B<mode> is "r", the file is opened for reading, and processing
+is set up to begin at the specified extension. For reading,
+B<name> can be B<stdin>, in which case the standard input is read.
+
+
+If B<mode> is "w", the file is created if it does not exist, or
+opened and truncated for writing if it does exist. Processing starts
+at the beginning of the file.  The B<name> can be B<stdout>,
+in which case the standard output is readied for processing.
+
+
+If B<mode> is "a", the file is created if it does not exist, or
+opened if it does exist. Processing starts at the end of the file.
+The B<name> can be B<stdout>, in which case the standard
+output is readied for processing.
+
+
+When a Funtools file is opened for writing or appending, a previously
+opened Funtools reference
+handle can be specified as the third argument. This handle
+typically is associated with the input Funtools file that will be used
+to generate the data for the output data.  When a reference file is
+specified in this way, the output file will inherit the (extension)
+header parameters from the input file:
+
+  Fun fun, fun2;
+  ...
+  /* open input file */
+  if( !(fun = FunOpen(argv[1], "r", NULL)) )
+    gerror(stderr, "could not FunOpen input file: %s\n", argv[1]);
+  /* open the output FITS image, inheriting params from input */
+  if( !(fun2 = FunOpen(argv[2], "w", fun)) )
+    gerror(stderr, "could not FunOpen output file: %s\n", argv[2]);
+
+Thus, in the above example, the output FITS binary table file will
+inherit all of the parameters associated with the input binary table
+extension.
+
+A file opened for writing with a 
+Funtools reference handle also
+inherits the selected columns (i.e. those columns chosen for
+processing using the 
+FunColumnSelect() routine)
+from the reference file as its default columns. This makes it easy to
+open an output file in such a way that the columns written to the
+output file are the same as the columns read in the input file. Of
+course, column selection can easily be tailored using the 
+FunColumnSelect() routine.
+In particular, it is easy to merge user-defined columns with the input
+columns to generate a new file.  See the 
+evmerge for a complete example.
+
+
+In addition, when a
+Funtools reference handle
+is supplied in a FunOpen() call,
+it is possible also to specify that all other extensions from the
+reference file (other than the input extension being processed) should
+be copied from the reference file to the output file. This is useful,
+for example, in a case where you are processing a FITS binary table 
+or image and you want to copy all of the other extensions to
+the output file as well.  Copy of other extensions is controlled by
+adding a "C" or "c" to the mode string of the 
+FunOpen() call of the input
+reference file.  If "C" is specified, then other extensions are
+B<always> copied (i.e., copy is forced by the application).  If
+"c" is used, then other extensions are copied if the user requests
+copying by adding a plus sign "+" to the extension name in the bracket
+specification.  For example, the B<funtable> program utilizes
+"c" mode, giving users the option of copying all other extensions:
+
+  /* open input file -- allow user copy of other extensions */
+  if( !(fun = FunOpen(argv[1], "rc", NULL)) )
+    gerror(stderr, "could not FunOpen input file: %s\n", argv[1]);
+  /* open the output FITS image, inheriting params from input */
+  if( !(fun2 = FunOpen(argv[2], "w", fun)) )
+    gerror(stderr, "could not FunOpen output file: %s\n", argv[2]);
+
+
+Thus, B<funtable> supports either of these command lines:
+
+  # copy only the EVENTS extension
+  csh> funtable "test.ev[EVENTS,circle(512,512,10)]" foo.ev
+  # copy ALL extensions
+  csh> funtable "test.ev[EVENTS+,circle(512,512,10)]" foo.ev
+
+
+
+Use of a Funtools reference
+handle implies that the input file is opened before the output
+file.  However, it is important to note that if copy mode ("c" or "C")
+is specified for the input file, the actual input file open is delayed
+until just after the output file is opened, since the copy of prior
+extensions to the output file takes place while Funtools is seeking to
+the specified input extension.  This implies that the output file
+should be opened before any I/O is done on the input file or else the
+copy will fail.  Note also that the copy of subsequent extension will
+be handled automatically by
+FunClose()
+if the output file is
+closed before the input file. Alternatively, it can be done explicitly
+by FunFlush(), but again, this
+assumes that the input file still is open.
+
+
+Upon success FunOpen() returns a
+Fun handle that is used in subsequent Funtools calls. On error, NULL
+is returned.
+
+
+
+
+=head1 SEE ALSO
+
+
+
+See funtools(n) for a list of Funtools help pages
+
+
+=cut