NAME¶
FunEnv - Funtools Environment Variables
SYNOPSIS¶
Describes the environment variables which can be used to tailor the overall
Funtools environment.
DESCRIPTION¶
The following environment variables are supported by Funtools:
- •
- FITS_EXTNAME
The FITS_EXTNAME environment variable specifies the default FITS
extension name when FunOpen() is called on a file lacking a primary
image. Thus,
setenv FITS_EXTNAME "NEWEV"
will allow you to call FunOpen() on files without specifying NEWEV in
the Funtools bracket specification. If no FITS_EXTNAME variable is defined
and the extension name also is not passed in the bracket specification,
then the default will be to look for standard X\-ray event table extension
names "EVENTS" or "STDEVT" (we are, after all, and
X\-ray astronomy group at heart!).
- •
- FITS_EXTNUM
The FITS_EXTNUM environment variable specifies the default FITS
extension number when FunOpen() is called on a file lacking a
primary image. Thus,
setenv FITS_EXTNUM 7
will allow you to call FunOpen() on files to open the seventh
extension without specifying the number in the Funtools bracket
specification.
- •
- FITS_BINCOLS and EVENTS_BINCOLS
These environment variable specifies the default binning key for FITS binary
tables and raw event files, respectively. They can be over-ridden using
the bincols=[naxis1,naxis2] keyword in a Funtools bracket
specification. The value of each environment variable is a pair of
comma-delimited columns, enclosed in parentheses, to use for binning. For
example, if you want to bin on detx and dety by default, then use:
setenv FITS_BINCOLS "(detx,dety)"
in preference to adding a bincols specification to each filename:
foo.fits[bincols=(detx,dety)]
- •
- FITS_BITPIX and EVENTS_BITPIX
These environment variable specifies the default bitpix value for binning
FITS binary tables and raw event files, respectively. They can be
over-ridden using the bitpix=[value] keyword in a Funtools bracket
specification. The value of each environment variable is one of the
standard FITS bitpix values (8,16,32,\-32,\-64). For example, if you want
binning routines to create a floating array, then use:
setenv FITS_BITPIX -32
in preference to adding a bitpix specification to each filename:
foo.fits[bitpix=-32]
- •
- ARRAY
The ARRAY environment variable specifies the default definition of an
array file for Funtools. It is used if there is no array specification
passed in the ARRAY() directive in a Non-FITS
Array specification. The value of the environment variable is a valid
array specification such as:
setenv ARRAY "s100.150"
foo.arr[ARRAY()]
This can be defined in preference to adding the specification to each
filename:
foo.arr[ARRAY(s100.150)]
- •
- EVENTS
The EVENTS environment variable specifies the default definition of
an raw event file for Funtools. It is used if there is no EVENTS
specification passed in the EVENTS() directive
in a Non-FITS EVENTS specification. The value of the environment variable
is a valid EVENTS specification such as:
setenv EVENTS "x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024"
foo.ev[EVENTS()]
This can be defined in preference to adding the specification to each
filename:
foo.ev[EVENTS(x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024)]
The following filter-related environment variables are supported by Funtools:
- •
- FILTER_PTYPE
The FILTER_PTYPE environment variable specifies how to build a
filter. There are three possible methods:
- •
- process or p
The filter is compiled and linked against the funtools library (which must
therefore be accessible in the original install directory) to produce a
slave program. This program is fed events or image data and returns filter
results.
- •
- dynamic or d (gcc only)
The filter is compiled and linked against the funtools library (which must
therefore be accessible in the original install directory) to produce a
dynamic shared object, which is loaded into the funtools program and
executed as a subroutine. (Extensive testing has shown that, contrary to
expectations, this method is no faster than using a slave process.)
- •
- contained or c
The filter and all supporting region code is compiled and linked without
reference to the funtools library to produce a slave program (which is fed
events or image data and returns filter results). This method is slower
than the other two, because of the time it takes to compile the region
filtering code. It is used by stand-alone programs such as ds9, which do
not have access to the funtools library.
By default,
dynamic is generally used for gcc compilers and
process for other compilers. However the filter building algorithm will
check for required external files and will use
contained is these are
missing.
- •
- FUN_MAXROW
The FUN_MAXROW environment variable is used by core row-processing
Funtools programs (funtable, fundisp, funcnts, funhist, funmerge, and
funcalc) to set the maximum number of rows read at once (i.e. it sets the
third argument to the FunTableRowGet() call). The default is 8192.
Note that this variable is a convention only: it will not be a part of a
non-core Funtools program unless code is explicitly added, since each call
to FunTableRowGet() specifies its own maximum number of rows to
read. NB: if you make this value very large, you probably will need to
increase FUN_MAXBUFSIZE (see below) as well.
- •
- FUN_MAXBUFSIZE
The FUN_MAXBUFSIZE environment variable is used to limit the max
buffer size that will be allocated to hold table row data. This buffer
size is calculated to be the row size of the table multiplied by the
maximum number of rows read at once (see above). Since the row size is
unlimited (and we have examples of it being larger than 5 Mb), it is
possible that the total buffer size will exceed the machine capabilities.
We therefore set a default value of 5Mb for the max buffer size, and
adjust maxrow so that the total size calculated is less than this max
buffer size. (If the row size is greater than this max buffer size, then
maxrow is set to 1.) This environment variable will change the max buffer
size allowed.
- •
- FILTER_CC
The FILTER_CC environment variable specifies the compiler to use for
compiling a filter specification. You also can use the CC
environment variable. If neither has been set, then gcc will be used if
available. Otherwise cc is used if available.
- •
- FILTER_EXTRA
The FILTER_EXTRA environment variable specifies extra options to add
to a filter compile command line. In principle, you can add libraries,
include files, and compiler switches. This variable should be used with
care.
- •
- FILTER_TMPDIR
The FILTER_TMPDIR environment variable specifies the temporary
directory for filter compilation intermediate files. You also can use the
TMPDIR and TMP variables. By default, /tmp is used as the
temporary directory.
- •
- FILTER_KEEP
The FILTER_KEEP environment variable specifies whether the
intermediate filter files (i.e. C source file and compile log file) should
be saved after a filter is built. The default is "false", so
that these intermediate files are deleted. This variable is useful for
debugging, but care should be taken to reset its value to false when
debugging is complete.
SEE ALSO¶
See
funtools(7) for a list of Funtools help pages