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