1funopen(3)                    SAORD Documentation                   funopen(3)
2
3
4

NAME

6       FunOpen - open a Funtools data file
7

SYNOPSIS

9         #include <funtools.h>
10
11         Fun FunOpen(char *name, char *mode, Fun ref);
12

DESCRIPTION

14       The FunOpen() routine opens a Funtools data file for reading or append‐
15       ing, or creates a new FITS file for writing. The name argument speci‐
16       fies the name of the Funtools data file to open. You can use IRAF-style
17       bracket notation to specify Funtools Files, Extensions, and Filters.  A
18       separate call should be made each time a different FITS extension is
19       accessed:
20
21         Fun fun;
22         char *iname;
23         ...
24         if( !(fun = FunOpen(iname, "r", NULL)) ){
25           fprintf(stderr, "could not FunOpen input file: %s\n", iname);
26           exit(1);
27         }
28
29       If mode is "r", the file is opened for reading, and processing is set
30       up to begin at the specified extension. For reading, name can be stdin,
31       in which case the standard input is read.
32
33       If mode is "w", the file is created if it does not exist, or opened and
34       truncated for writing if it does exist. Processing starts at the begin‐
35       ning of the file.  The name can be stdout, in which case the standard
36       output is readied for processing.
37
38       If mode is "a", the file is created if it does not exist, or opened if
39       it does exist. Processing starts at the end of the file.  The name can
40       be stdout, in which case the standard output is readied for processing.
41
42       When a Funtools file is opened for writing or appending, a previously
43       opened Funtools reference handle can be specified as the third argu‐
44       ment. This handle typically is associated with the input Funtools file
45       that will be used to generate the data for the output data.  When a
46       reference file is specified in this way, the output file will inherit
47       the (extension) header parameters from the input file:
48
49         Fun fun, fun2;
50         ...
51         /* open input file */
52         if( !(fun = FunOpen(argv[1], "r", NULL)) )
53           gerror(stderr, "could not FunOpen input file: %s\n", argv[1]);
54         /* open the output FITS image, inheriting params from input */
55         if( !(fun2 = FunOpen(argv[2], "w", fun)) )
56           gerror(stderr, "could not FunOpen output file: %s\n", argv[2]);
57
58       Thus, in the above example, the output FITS binary table file will
59       inherit all of the parameters associated with the input binary table
60       extension.
61
62       A file opened for writing with a Funtools reference handle also inher‐
63       its the selected columns (i.e. those columns chosen for processing
64       using the FunColumnSelect() routine) from the reference file as its
65       default columns. This makes it easy to open an output file in such a
66       way that the columns written to the output file are the same as the
67       columns read in the input file. Of course, column selection can easily
68       be tailored using the FunColumnSelect() routine.  In particular, it is
69       easy to merge user-defined columns with the input columns to generate a
70       new file.  See the evmerge for a complete example.
71
72       In addition, when a Funtools reference handle is supplied in a
73       FunOpen() call, it is possible also to specify that all other exten‐
74       sions from the reference file (other than the input extension being
75       processed) should be copied from the reference file to the output file.
76       This is useful, for example, in a case where you are processing a FITS
77       binary table or image and you want to copy all of the other extensions
78       to the output file as well.  Copy of other extensions is controlled by
79       adding a "C" or "c" to the mode string of the FunOpen() call of the
80       input reference file.  If "C" is specified, then other extensions are
81       always copied (i.e., copy is forced by the application).  If "c" is
82       used, then other extensions are copied if the user requests copying by
83       adding a plus sign "+" to the extension name in the bracket specifica‐
84       tion.  For example, the funtable program utilizes "c" mode, giving
85       users the option of copying all other extensions:
86
87         /* open input file -- allow user copy of other extensions */
88         if( !(fun = FunOpen(argv[1], "rc", NULL)) )
89           gerror(stderr, "could not FunOpen input file: %s\n", argv[1]);
90         /* open the output FITS image, inheriting params from input */
91         if( !(fun2 = FunOpen(argv[2], "w", fun)) )
92           gerror(stderr, "could not FunOpen output file: %s\n", argv[2]);
93
94       Thus, funtable supports either of these command lines:
95
96         # copy only the EVENTS extension
97         csh> funtable "test.ev[EVENTS,circle(512,512,10)]" foo.ev
98         # copy ALL extensions
99         csh> funtable "test.ev[EVENTS+,circle(512,512,10)]" foo.ev
100
101       Use of a Funtools reference handle implies that the input file is
102       opened before the output file.  However, it is important to note that
103       if copy mode ("c" or "C") is specified for the input file, the actual
104       input file open is delayed until just after the output file is opened,
105       since the copy of prior extensions to the output file takes place while
106       Funtools is seeking to the specified input extension.  This implies
107       that the output file should be opened before any I/O is done on the
108       input file or else the copy will fail.  Note also that the copy of sub‐
109       sequent extension will be handled automatically by FunClose() if the
110       output file is closed before the input file. Alternatively, it can be
111       done explicitly by FunFlush(), but again, this assumes that the input
112       file still is open.
113
114       Upon success FunOpen() returns a Fun handle that is used in subsequent
115       Funtools calls. On error, NULL is returned.
116

SEE ALSO

118       See funtools(n) for a list of Funtools help pages
119
120
121
122version 1.4.0                   August 15, 2007                     funopen(3)
Impressum