1funenv(n) SAORD Documentation funenv(n)
2
6 FunEnv: Funtools Environment Variables
7
9 Describes the environment variables which can be used to tailor the
10 overall Funtools environment.
11
13 The following environment variables are supported by Funtools:
14 · FITS_EXTNAME
16 The FITS_EXTNAME environment variable specifies the default FITS
18 extension name when FunOpen() is called on a file lacking a primary
19 image. Thus,
20 setenv FITS_EXTNAME "NEWEV"
22 will allow you to call FunOpen() on files without specifying NEWEV
24 in the Funtools bracket specification. If no FITS_EXTNAME variable
25 is defined and the extension name also is not passed in the bracket
26 specification, then the default will be to look for standard X-ray
27 event table extension names "EVENTS" or "STDEVT" (we are, after
28 all, and X-ray astronomy group at heart!).
29 · FITS_EXTNUM
31 The FITS_EXTNUM environment variable specifies the default FITS
33 extension number when FunOpen() is called on a file lacking a pri‐
34 mary image. Thus,
35 setenv FITS_EXTNUM 7
37 will allow you to call FunOpen() on files to open the seventh
39 extension without specifying the number in the Funtools bracket
40 specification.
41 · FITS_BINCOLS and EVENTS_BINCOLS
43 These environment variable specifies the default binning key for
45 FITS binary tables and raw event files, respectively. They can be
46 over-ridden using the bincols=[naxis1,naxis2] keyword in a Funtools
47 bracket specification. The value of each environment variable is a
48 pair of comma-delimited columns, enclosed in parentheses, to use
49 for binning. For example, if you want to bin on detx and dety by
50 default, then use:
51 setenv FITS_BINCOLS "(detx,dety)"
53 in preference to adding a bincols specification to each filename:
55 foo.fits[bincols=(detx,dety)]
57 · FITS_BITPIX and EVENTS_BITPIX
59 These environment variable specifies the default bitpix value for
61 binning FITS binary tables and raw event files, respectively. They
62 can be over-ridden using the bitpix=[value] keyword in a Funtools
63 bracket specification. The value of each environment variable is
64 one of the standard FITS bitpix values (8,16,32,-32,-64). For
65 example, if you want binning routines to create a floating array,
66 then use:
67 setenv FITS_BITPIX -32
69 in preference to adding a bitpix specification to each filename:
71 foo.fits[bitpix=-32]
73 · ARRAY
75 The ARRAY environment variable specifies the default definition of
77 an array file for Funtools. It is used if there is no array speci‐
78 fication passed in the ARRAY() directive in a Non-FITS Array speci‐
79 fication. The value of the environment variable is a valid array
80 specification such as:
81 setenv ARRAY "s100.150"
83 foo.arr[ARRAY()]
84 This can be defined in preference to adding the specification to
86 each filename:
87 foo.arr[ARRAY(s100.150)]
89 · EVENTS
91 The EVENTS environment variable specifies the default definition of
93 an raw event file for Funtools. It is used if there is no EVENTS
94 specification passed in the EVENTS() directive in a Non-FITS EVENTS
95 specification. The value of the environment variable is a valid
96 EVENTS specification such as:
97 setenv EVENTS "x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024"
99 foo.ev[EVENTS()]
100 This can be defined in preference to adding the specification to
102 each filename:
103 foo.ev[EVENTS(x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024)]
105 The following filter-related environment variables are supported by
107 Funtools:
108 · FILTER_PTYPE
110 The FILTER_PTYPE environment variable specifies how to build a fil‐
112 ter. There are three possible methods:
113 · process or p
115 The filter is compiled and linked against the funtools library
117 (which must therefore be accessible in the original install
118 directory) to produce a slave program. This program is fed
119 events or image data and returns filter results.
120 · dynamic or d (gcc only)
122 The filter is compiled and linked against the funtools library
124 (which must therefore be accessible in the original install
125 directory) to produce a dynamic shared object, which is loaded
126 into the funtools program and executed as a subroutine. (Exten‐
127 sive testing has shown that, contrary to expectations, this
128 method is no faster than using a slave process.)
129 · contained or c
131 The filter and all supporting region code is compiled and
133 linked without reference to the funtools library to produce a
134 slave program (which is fed events or image data and returns
135 filter results). This method is slower than the other two,
136 because of the time it takes to compile the region filtering
137 code. It is used by stand-alone programs such as ds9, which do
138 not have access to the funtools library.
139 By default, dynamic is generally used for gcc compilers and process
141 for other compilers. However the filter building algorithm will
142 check for required external files and will use contained is these
143 are missing.
144 · FUN_MAXROW
146 The FUN_MAXROW environment variable is used by core row-processing
148 Funtools programs (funtable, fundisp, funcnts, funhist, funmerge,
149 and funcalc) to set the maximum number of rows read at once (i.e.
150 it sets the third argument to the FunTableRowGet() call). The
151 default is 8192. Note that this variable is a convention only: it
152 will not be a part of a non-core Funtools program unless code is
153 explicitly added, since each call to FunTableRowGet() specifies its
154 own maximum number of rows to read. NB: if you make this value very
155 large, you probably will need to increase FUN_MAXBUFSIZE (see
156 below) as well.
157 · FUN_MAXBUFSIZE
159 The FUN_MAXBUFSIZE environment variable is used to limit the max
161 buffer size that will be allocated to hold table row data. This
162 buffer size is calculated to be the row size of the table multi‐
163 plied by the maximum number of rows read at once (see above). Since
164 the row size is unlimited (and we have examples of it being larger
165 than 5 Mb), it is possible that the total buffer size will exceed
166 the machine capabilities. We therefore set a default value of 5Mb
167 for the max buffer size, and adjust maxrow so that the total size
168 calculated is less than this max buffer size. (If the row size is
169 greater than this max buffer size, then maxrow is set to 1.) This
170 environment variable will change the max buffer size allowed.
171 · FILTER_CC
173 The FILTER_CC environment variable specifies the compiler to use
175 for compiling a filter specification. You also can use the CC envi‐
176 ronment variable. If neither has been set, then gcc will be used if
177 available. Otherwise cc is used if available.
178 · FILTER_EXTRA
180 The FILTER_EXTRA environment variable specifies extra options to
182 add to a filter compile command line. In principle, you can add
183 libraries, include files, and compiler switches. This variable
184 should be used with care.
185 · FILTER_TMPDIR
187 The FILTER_TMPDIR environment variable specifies the temporary
189 directory for filter compilation intermediate files. You also can
190 use the TMPDIR and TMP variables. By default, /tmp is used as the
191 temporary directory.
192 · FILTER_KEEP
194 The FILTER_KEEP environment variable specifies whether the interme‐
196 diate filter files (i.e. C source file and compile log file) should
197 be saved after a filter is built. The default is "false", so that
198 these intermediate files are deleted. This variable is useful for
199 debugging, but care should be taken to reset its value to false
200 when debugging is complete.
201
203 See funtools(n) for a list of Funtools help pages
204version 1.4.0 August 15, 2007 funenv(n)