diff options
Diffstat (limited to 'funtools/doc/env.html')
| -rw-r--r-- | funtools/doc/env.html | 222 |
1 files changed, 222 insertions, 0 deletions
diff --git a/funtools/doc/env.html b/funtools/doc/env.html new file mode 100644 index 0000000..c060017 --- /dev/null +++ b/funtools/doc/env.html @@ -0,0 +1,222 @@ +<!-- =defdoc funenv funenv n --> +<HTML> +<HEAD> +<TITLE>Funtools Environment Variables</TITLE> +</HEAD> +<BODY> + +<!-- =section funenv NAME --> +<H2><A NAME="funenv">FunEnv: Funtools Environment Variables</A></H2> + +<!-- =section funenv SYNOPSIS --> +<H2>Summary</H2> +Describes the environment variables which can be used to tailor the overall +Funtools environment. + +<!-- =section funenv DESCRIPTION --> +<H2>Description</H2> +<P> +The following environment variables are supported by Funtools: +<DL> +<P> +<DT><B>FITS_EXTNAME</B> +<DD> The <B>FITS_EXTNAME</B> environment variable specifies the +default FITS extension name when <A HREF="./library.html#funopen">FunOpen()</A> is called on a file lacking +a primary image. Thus, +<PRE> + setenv FITS_EXTNAME "NEWEV" +</PRE> +will allow you to call <A HREF="./library.html#funopen">FunOpen()</A> on files without specifying NEWEV in +the +<A HREF="./files.html">Funtools bracket specification</A>. +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!). + +<P> +<DT><B>FITS_EXTNUM</B> +<DD> The <B>FITS_EXTNUM</B> environment variable specifies the +default FITS extension number when <A HREF="./library.html#funopen">FunOpen()</A> is called on a file lacking +a primary image. Thus, +<PRE> + setenv FITS_EXTNUM 7 +</PRE> +will allow you to call <A HREF="./library.html#funopen">FunOpen()</A> on files to open the seventh +extension without specifying the number in the +<A HREF="./files.html">Funtools bracket specification</A>. + +<P> +<DT><B>FITS_BINCOLS</B> and <B>EVENTS_BINCOLS</B> +<DD> 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]</B> keyword in a +<A HREF="./files.html">Funtools bracket specification</A>. +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: +<PRE> + setenv FITS_BINCOLS "(detx,dety)" +</PRE> +in preference to adding a bincols specification to each filename: +<PRE> + foo.fits[bincols=(detx,dety)] +</PRE> + +<P> +<DT><B>FITS_BITPIX</B> and <B>EVENTS_BITPIX</B> +<DD> 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]</B> keyword in a +<A HREF="./files.html">Funtools bracket specification</A>. 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: +<PRE> + setenv FITS_BITPIX -32 +</PRE> +in preference to adding a bitpix specification to each filename: +<PRE> + foo.fits[bitpix=-32] +</PRE> + +<P> +<DT><B>ARRAY</B> +<DD> The <B>ARRAY</B> 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()</B> directive in a +<A HREF="./files.html#arrays">Non-FITS Array specification</A>. +The value of the environment variable is a valid array specification such as: +<PRE> + setenv ARRAY "s100.150" + foo.arr[ARRAY()] +</PRE> +This can be defined in preference to adding the specification to each filename: +<PRE> + foo.arr[ARRAY(s100.150)] +</PRE> + +<P> +<DT><B>EVENTS</B> +<DD> The <B>EVENTS</B> 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()</B> directive in a +<A HREF="./files.html#events">Non-FITS EVENTS specification</A>. +The value of the environment variable is a valid EVENTS specification such as: +<PRE> + setenv EVENTS "x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024" + foo.ev[EVENTS()] +</PRE> +This can be defined in preference to adding the specification to each filename: +<PRE> + foo.ev[EVENTS(x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024)] +</PRE> +</DL> + +The following filter-related environment variables are supported by Funtools: +<DL> + +<P> +<DT><B>FILTER_PTYPE</B> +<DD> The <B>FILTER_PTYPE</B> environment variable specifies how to +build a filter. There are three possible methods: +<DL> +<DT>process or p +<DD>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. + +<DT>dynamic or d (gcc only) +<DD>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.) + +<DT>contained or c +<DD>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. +</DL> + +By default, <B>dynamic</B> is generally used for gcc compilers and +<B>process</B> for other compilers. However the filter building algorithm +will check for required external files and will use <B>contained</B> is +these are missing. + +<P> +<DT><B>FUN_MAXROW</B> +<DD> The <B>FUN_MAXROW</B> 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</B> (see below) as well. + +<P> +<DT><B>FUN_MAXBUFSIZE</B> +<DD> The <B>FUN_MAXBUFSIZE</B> 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. + +<P> +<DT><B>FILTER_CC</B> +<DD> The <B>FILTER_CC</B> environment variable specifies the compiler to +use for compiling a filter specification. You also can use the <B>CC</B> +environment variable. If neither has been set, then gcc will be used +if available. Otherwise cc is used if available. + +<P> +<DT><B>FILTER_EXTRA</B> +<DD> The <B>FILTER_EXTRA</B> 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. + +<P> +<DT><B>FILTER_TMPDIR</B> +<DD> The <B>FILTER_TMPDIR</B> environment variable specifies the temporary +directory for filter compilation intermediate files. You also can use +the <B>TMPDIR</B> and <B>TMP</B> variables. By default, /tmp is used +as the temporary directory. + +<P> +<DT><B>FILTER_KEEP</B> +<DD> The <B>FILTER_KEEP</B> 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. + +</DL> + +<!-- =section funenv SEE ALSO --> +<!-- =text See funtools(n) for a list of Funtools help pages --> +<!-- =stop --> + +<P> +<A HREF="./help.html">Go to Funtools Help Index</A> + +<H5>Last updated: November 16, 2005</H5> + +</BODY> +</HTML> + |