Input

All input to HEASOFT tasks is controlled by a parameter interface library (APE) which is developed and maintained by the HEASARC, but was originally based on the INTEGRAL Science Data Center's "PIL" code. APE has a very similar look and feel to XPI (the original parameter interface used in FTOOLS) but includes such additional features as enumerated values, minimum-maximum range checking, the ability to use environment variables in parameters and a dedicated "filename" type. APE is callable by C, C++, Fortran and Perl tasks.

There are three commonly-used parameters which are handled intrinsically by the internal HEASOFT initialization routines and thus developers do not need to explicitly read them at the individual task level. (A fourth parameter, "mode", is an APE internal and operates exactly as in XPI). The standard HEASOFT parameters are:

• CHATTER The (integer) "chatter" parameter may be used to control the verbosity of a HEASOFT task. (This is similar to the "verbose" parameter used e.g. in CIAO, however, since a number of FTOOLS tasks use "chatter" we have chosen to keep the same name for consistency across the HEASOFT suite.) Developers are free to specify any range (via the parameter min/max) but we recommend the following (0-5):

  0 suppresses all but absolutely essential output

  1-4 normal levels. The different levels can be used on a task by task basis to control the amount of output information. The distinction between the different chatter levels (if any) must be documented in the task's help file. For many tasks, all 4 chatter levels might produce exactly the same output.

  5 debug mode: prints detailed messages about each step in the program

  The desired chatter value will be specified by the user at runtime and read automatically during the initialization phase. The task developer may then funnel diagnostic output through the supplied routines (see output section below) which take as their first argument a threshold chatter level below which the output will be suppressed. A chatter parameter is not required for any task, however, calling headas_chat()/hdchat() in a task having no chatter parameter will result in an error.

• CLOBBER

  If a (boolean) "clobber" parameter is present for a given task it will be read during the initialization phase. Developers may then call headas_clobberfile(filename) which will delete the specified file if it exists and if the "clobber" parameter was set to "yes". Note that an alternative to clobber exists for FITS files since CFITSIO will clobber any file which begins with the "!" character.

• HISTORY

  The (boolean) "history" parameter controls whether or not the user wishes to allow a set of HISTORY keywords listing the runtime values of all task parameters to be written into any FITS file header. The developer simply calls HDpar_stamp() specifying the desired FITS file and extension and, if the history parameter value at runtime permits it, the HISTORY block will be written. If the task has no history parameter then a call to HDpar_stamp() will return an error. Each HISTORY keyword block will be clearly delimited and will include the task name/version and a timestamp. Use of HDpar_stamp() is not required, but is recommended both as a means of documenting the runtime conditions and as input for a planned utility which can rerun any task using the information recorded in the HISTORY block.