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

version 1.4.5                                    April 14, 2011                                       funopen(3)