NAME

       FunOpen - open a Funtools data file

SYNOPSIS

         #include <funtools.h>

         Fun FunOpen(char *name, char *mode, Fun ref);

DESCRIPTION

       The FunOpen() routine opens a Funtools data file for reading or appending, or creates a
       new FITS file for writing. The 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 mode is "r", the file is opened for reading, and processing is set up to begin at the
       specified extension. For reading, name can be stdin, in which case the standard input is
       read.

       If 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 name can be
       stdout, in which case the standard output is readied for processing.

       If 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 name can be 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 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 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, 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.

SEE ALSO

       See funtools(7) for a list of Funtools help pages