1 files changed, 349 insertions, 0 deletions
diff --git a/funtools/doc/pod/funenv.pod b/funtools/doc/pod/funenv.pod
new file mode 100644
index 0000000..0717a17
--- /dev/null
+++ b/funtools/doc/pod/funenv.pod
@@ -0,0 +1,349 @@
+=pod
+
+=head1 NAME
+
+
+
+B<FunEnv: Funtools Environment Variables>
+
+
+
+=head1 SYNOPSIS
+
+
+
+
+Describes the environment variables which can be used to tailor the overall
+Funtools environment.
+
+
+
+=head1 DESCRIPTION
+
+
+
+
+
+The following environment variables are supported by Funtools:
+
+
+=over 4
+
+
+
+
+
+=item *
+
+B<FITS_EXTNAME>
+
+
+The B<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!).
+
+
+
+
+=item *
+
+B<FITS_EXTNUM>
+
+
+The B<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.
+
+
+
+
+=item *
+
+B<FITS_BINCOLS> and B<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 B<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)]
+
+
+
+
+
+=item *
+
+B<FITS_BITPIX> and B<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 B<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]
+
+
+
+
+
+=item *
+
+B<ARRAY>
+
+
+The B<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
+B<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)]
+
+
+
+
+
+=item *
+
+B<EVENTS>
+
+
+The B<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
+B<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)]
+
+
+
+=back
+
+
+
+The following filter-related environment variables are supported by Funtools:
+
+
+=over 4
+
+
+
+
+
+
+=item *
+
+B<FILTER_PTYPE>
+
+
+The B<FILTER_PTYPE> environment variable specifies how to
+build a filter.  There are three possible methods:
+
+
+=over 4
+
+
+
+
+=item *
+
+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.
+
+
+
+=item *
+
+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.)
+
+
+
+=item *
+
+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.
+
+
+=back
+
+
+
+By default, B<dynamic> is generally used for gcc compilers and
+B<process> for other compilers. However the filter building algorithm
+will check for required external files and will use B<contained> is
+these are missing.
+
+
+
+
+=item *
+
+B<FUN_MAXROW>
+
+
+The B<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 B<FUN_MAXBUFSIZE> (see below) as well.
+
+
+
+
+=item *
+
+B<FUN_MAXBUFSIZE>
+
+
+The B<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.
+
+
+
+
+=item *
+
+B<FILTER_CC>
+
+
+The B<FILTER_CC> environment variable specifies the compiler to
+use for compiling a filter specification. You also can use the B<CC>
+environment variable. If neither has been set, then gcc will be used
+if available. Otherwise cc is used if available.
+
+
+
+
+=item *
+
+B<FILTER_EXTRA>
+
+
+The B<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.
+
+
+
+
+=item *
+
+B<FILTER_TMPDIR>
+
+
+The B<FILTER_TMPDIR> environment variable specifies the temporary
+directory for filter compilation intermediate files. You also can use
+the B<TMPDIR> and B<TMP> variables. By default, /tmp is used
+as the temporary directory.
+
+
+
+
+=item *
+
+B<FILTER_KEEP>
+
+
+The B<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.
+
+
+
+=back
+
+
+
+
+
+=head1 SEE ALSO
+
+
+
+See funtools(n) for a list of Funtools help pages
+
+
+
+=cut