funenv(7)							SAORD Documentation							 funenv(7)

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:

       o   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!).

       o   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 specifi-
	   cation.

       o   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)]

       o   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]

       o   ARRAY

	   The ARRAY environment variable specifies the default definition of an array file for Funtools.  It is used if there is no array speci-
	   fication 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)]

       o   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:

       o   FILTER_PTYPE

	   The FILTER_PTYPE environment variable specifies how to build a filter.  There are three possible methods:

	   o   process or p

	       The filter is compiled and linked against the funtools library (which must therefore be accessible in the original install direc-
	       tory) to produce a slave program. This program is fed events or image data and returns filter results.

	   o   dynamic or d (gcc only)

	       The filter is compiled and linked against the funtools library (which must therefore be accessible in the original install direc-
	       tory) to produce a dynamic shared object, which is loaded into the funtools program and executed as a subroutine. (Extensive test-
	       ing has shown that, contrary to expectations, this method is no faster than using a slave process.)

	   o   contained or c

	       The filter and all supporting region code is compiled and linked without reference to the funtools library to produce a slave pro-
	       gram (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 fun-
	       tools 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.

       o   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.

       o   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 buf-
	   fer 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 calcu-
	   lated 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 environ-
	   ment variable will change the max buffer size allowed.

       o   FILTER_CC

	   The FILTER_CC environment variable specifies the compiler to use for compiling a filter specification. You also can use the CC environ-
	   ment variable. If neither has been set, then gcc will be used if available. Otherwise cc is used if available.

       o   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.

       o   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.

       o   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

version 1.4.2							  January 2, 2008							 funenv(7)