Introduction

HEAdas refers to a new component in HEASoft, the LHEA software suite which currently encompasses FTOOLS and XANADU (ie, XSPEC, XRONOS, and XIMAGE). HEAdas tasks are virtually identical in look-and-feel to FTOOLS from a user's perspective but are, in fact, built around a completely distinct core (with the exception of the CFITSIO library). This new package is intended to be simpler and leaner than FTOOLS, as well as more portable, stable and extensible.

HEAdas is composed of two basic parts: a mission-independent set of general FITS utilities (HEAtools) which is being developed within the HEASARC, as well as a set of mission-specific packages developed and maintained (in whole or in part) by outside groups. The HEAdas core (including the HEAtools) is written entirely in ANSI C for maximum portability. Missions are, however, free to use any language they wish within their own package, bearing in mind that certain choices may limit the platforms and/or compilers on which their tasks will build and run.

Until HEAdas has fully matured it is likely that tasks (eg, Perl scripts) in the mission-specific packages will call tasks which still reside in the FTOOLS portion of HEASoft and software distributions by the HEASARC will generally include all necessary components in a single tar file to make things as easy for users as possible. However, in keeping with a modular approach (as well as to avoid incompatibility due to different release schedules) it is important that mission-specific tasks not link against FTOOLS libraries (eg, xanlib). If mission developers find that they require those subroutines in their tasks then they should be migrated to the appropriate HEAdas library. Whether that would be more appropriate to a core library versus a mission-specific library may require coordination and/or consultation with the HEASARC programming staff.

Configuration Management and HEADAS setup

All infrastructure and configuration management of HEAdas is handled by the HEASARC, including such things as Makefiles and configure scripts. Code revision control is handled via a central CVS repository resident on a HEASARC server. Developers of mission-specific software only have write access in the relevant portions of the repository but have read access to the entire package so that they can check-out as much of it as they wish for local testing. However, a limited number of HEASARC programmers have global write access to enable necessary configuration modifications. CVS includes automatic email notification of new check-ins so that developers will be informed of any changes to their portion of the repository as they occur.

The directory structure for any given subpackage is reasonably flexible so that mission software developers can arrange things to suit their own needs and/or preferences. Certain constraints may, however, be required to accomodate the overall HEAdas build paradigm.

Full, top-down builds are started from the headas/BUILD_DIR directory using the typical steps of ./configure followed by make and then finally make install. Unit test scripts may optionally be installed via a parallel make test and make install-test sequence. Internally, however, builds are managed by hmake, exactly as in the current FTOOLS package. This utility is designed to also make it easy to build all or part of the distribution on any supported platform without having to make modifications by hand specifying the location and/or names of necessary flags and libraries. That is, once a full build and install have been performed, a developer may simply checkout a copy of a particular tool and build it via the command hmake. Before using hmake one simply needs to be pointing at a completed HEAdas installation by setting the HEADAS environment variable and running the appropriate initialization script (eg, (assuming a cshell environment) source $HEADAS/headas-init.csh). The hmake utility should then be able to build any tool or library, automatically linking as needed against the libraries in the pointed-to installation and using the flags appropriate to that installation.

Input/Output

INPUT

All input to HEAdas tasks is controlled by the Parameter Interface Library (PIL) which is developed and maintained by the INTEGRAL Science Data Center. PIL has a very similar look and feel to XPI (the 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. PIL is callable by C, C++, f77 and f90 tasks. Full documentation for PIL is available in the source tree under headas/heacore/pil/doc.

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

• CHATTER
  
  The (integer) "chatter" parameter may be used to control the verbosity of a HEAdas task. (This is similar to the "verbose" parameter used in CIAO, however, since a number of FTOOLS tasks, especially in the caltools subpackage, 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 headas_parstamp() 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 headas_parstamp() will return an error. Each HISTORY keyword block will be clearly delimited and will include the task name/version and a timestamp. Use of headas_parstamp() 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. The headas_parstamp() utility now will also expand any ascii file specified using the '@filename' convention and will include the contents of that file in the HISTORY block.

OUTPUT

Diagnostic output and other text messages must be able to be separated from the standard output stream to enable, eg, piping FITS files between tasks. Developers should never write directly to stdout but should instead funnel screen output through the dedicated HEAdas streams. These streams are set up during task initialization and are controlled by environment variables. Task developers should never have to read or otherwise deal with these variables. The following methods for diagnostic output are currently available to developers writing tasks in C:

headas_printf(char *, ...)
Operates exactly like the stdio version of printf but the stream will be directed to the location specified by the environment variable HEADASOUTPUT (if present).

headas_chat(int, char *, ...)
Identical to headas_printf() except for an additional integer argument which specifies the threshold "chatter" level below which the message will be suppressed (depending on the runtime value of the chatter parameter, see discussion of "chatter" above).

fprintf(heaout, char *, ...)
The "heaout" stream (which replaces stdout in HEAdas) may be written to directly, as shown.

printf(char *, ...)
The usual stdio printf() routine can still be used (eg, in legacy code) but will be dynamically replaced by headas_printf() during compilation.

Fortran tasks should use the dedicated routines hdecho() and hdchat(). The former is exactly equivalent to the fcecho() routine in the FTOOLS package while the latter adds the chatter threshold argument as in headas_chat() above. Note that unlike the C versions above, formatting of the output strings must be done prior to calling hdecho()/hdchat(), eg, via an internal write.

Future GUI development and/or other enhancements to HEAdas will likely require that the standard error stream and parameter prompts be monitored and/or redirected as well. The environment variables HEADASERROR and HEADASPROMPT, respectively, control these but developers should not need to deal with them directly. C tasks may simply use fprintf(stderr, ...) to print error messages as usual, while Fortran tasks should use hderr() (which is exactly like the FTOOLS fcerr() routine). As with hdecho(), the output error message must be constructed internally prior to calling hderr().

General Notes

All tasks should:

• Follow ANSI standards (ie, C89 and X3J3/90.4 for C and Fortran77, respectively) for maximum portability.
• Be written as a subprogram (not a main) which returns an integer status value.
• (for C only) Contain the following block of code near the top of the task subroutine:

#include "fitsio.h" /* assuming CFITSIO routines will be called */
#include "pil.h" /* assuming PIL routines will be called */
#include "headas.h"

#define TOOLSUB my_task_subroutine_name /* use actual subroutine name here */
#include "headas_main.c"

• Check return status after all CFITSIO and PIL calls and use the relevant error reporting routine if status is non-zero.
• Register a task name and version number (see below).

Task Name/Version

Every HEAdas task should register its name and version number so that the information is available to other routines which may need it. A set of routines in the heautils library (see headas_toolname.c in the library inventory section, below) has been provided for this purpose. Each task should call set_toolname() and set_toolversion() to record the information and developers may retrieve the information via get_toolname()/get_toolversion() or by the simpler get_toolnamev() which returns both in a single string with name and version joined with an underscore. The Fortran equivalents are hdnameset(), hdverset(), hdnameget(), hdverget() and hdnamevget(). Note that a default name is recorded during task initialization based on the executable name. A default version number of "0.0" will likewise be used. These defaults will be superceded via calls at the task level to set_toolname() and set_toolversion().

CALDB Access

The HEASARC Calibration Database (CALDB) will be accessible to HEAdas tasks exactly as it is to FTOOLS and missions choosing to use HEAdas should plan on submitting their FITS calibration files for inclusion in the CALDB. However, because the main CALDB access routine, gtcalf(), is written in f77, however, it is being rewritten in ANSI C in keeping with the requirements of the HEAdas core. The method in which it is used will be exactly the same, making code migration from the FTOOLS system trivial. As in most of the routines discussed here, a Fortran wrapper will be provided so that they may be called from Fortran tasks too.

Scripting

All scripting should be done using Perl5. The HEASARC will provide Perl utilities to make it easy and convenient for scripts to call HEAdas and/or FTOOLS tasks, for example, to trap any runtime errors which may occur. We also expect to include the CFITSIO Perl module (CFITSIO.pm) in the distribution to allow for Perl scripts to directly call CFITSIO routines as well.

Expected Enhancements

In addition to the components already mentioned, the following are being evaluated for inclusion with the HEAdas package:

• CCfits: an object-oriented interface to the CFITSIO library designed to make the capabilities of CFITSIO available to programmers working in C++.

Library Inventory

The components of the directory "heacore" are:

• cfitsio (from the standard HEASARC distribution)
• pil (from the standard ISDC distribution)
• readline (from the standard GNU distribution)
• atFunctions (ISAS library of attitude-related routines)
• coord/coordfits (additional routines for attitude, coordinate transformations, etc.)
• Astro::FITS::CFITSIO (CFITSIO Perl module, distributed by Pete Ratzlaff (CfA))



• heainit
• headas.h
  Header file containing function prototypes, etc.
• headas_init.c
  Contains routines called internally -- developers should not need to call these explicitly:
  int headas_init(int, char **)
  Calls routines to initialize PIL and output streams. It also deals with standard headas parameters (chatter, clobber, history).
  int headas_close()
  Closes output streams and PIL.
  static void ReportError(int)
  Error stack handling.
  static int StandardPfile(int argc, char *argv[])
  Parameter file initialization.
  int hd_pil_err_logger(char *s)
  Default PIL error logging routine. Simply prints to stderr.

• headas_main.c
  This file comprises the main program unit for every task. It calls headas_init() followed by the task subroutine itself and then calls headas_close() after the task completes. This main routine is not part of any library and must be explicitly included by all C tasks (via #include "headas_main.c"). For f77 tasks it is automatically compiled and linked in by the Makefile.
• heaio
• headas_stdio.c
  Contains public C/C++ callable HEADAS replacemenets for C standard I/O facilities, including:
  int headas_printf(const char *, ...)
  Replaces the stdio printf() with identical arguments. Text is written to the location specified by the HEADASOUTPUT environment variable (if present) instead of to stdout.
  int headas_chat(int, const char *, ...)
  Same as headas_printf() but takes an integer argument which specifies the threshold chatter level below which the text will not be output.
  int pil_printf(const char *, ...)
  A substitute for printf() for internal use by PIL only. Should not be called by tasks directly. NOT CURRENTLY USED.
  void headas_f77echo(const char *)
  A f77-callable version of headas_printf(). It is called hdecho() from Fortran programs.
  void headas_f77err(const char *)
  A f77-callable version of fprintf(stderr, ...). Called hderr() from Fortran. This routine will write to the stderr stream (which may have been redirected via the HEADASERROR environment variable).
  void headas_f77chat(int, const char *)
  A f77-callable version of headas_chat(). It is called hdchat() from Fortran.

• heautils
• headas_utils.c
  Contains utility routines:
  int headas_parstamp(fitsfile *, int)
  Writes a block of HISTORY keywords into a FITS file header listing all the runtime parameter values. Arguments are a FITS file pointer and extension number. Callable from Fortran as hdparstamp().
  char *hdbasename(char *)
  Equivalent to the basename() function (returns the filename portion of an input pathname).
  int headas_clobberfile(char *)
  Deletes the specified file if it already exists and if the clobber parameter for the current task is set to "yes". Callable from Fortran as hdclobber().
  float hd_ran2(long *)
  Random number generator based on ran2() from Numerical Recipes in C, 2nd ed., p282. Returns a uniform random deviate between 0.0 and 1.0 (exclusive of the endpoint values). Call with a negative integer argument to initialize. Callable from Fortran as hd_ran2().
  char **expand_item_list(char *, int *, char, int, int, int, int *);
  Parses a delimited list or "@" file into individual strings. An array of string pointers is returned, one pointer for each item in the list. A delimited list is broken into one string per delimited element. The user can choose the delimiter character, often a comma. An "@" file is broken into one string per line of the file. The user can select whether leading and trailing blanks are trimmed or whether empty items are removed. Also, for a delimited list, the user can guard against delimiters embedded within CFITSIO vector syntax, as in the comma within "item1[x,y]".

• headas_error.c
  Contains routines to implement HEAdas basic error handling API functions. (see associated documentation).
• headas_error_init.c, headas_error_manager.c, headas_error_map.c
  Contains associated routines for HEAdas error handling. (see associated documentation).
• headas_toolname.c
  Contains routines to get/set the name/version of the current task:
  void set_toolname(const char *)
  Use this to register the task's name. The Fortran version is hdnameset().
  void get_toolname(char *)
  Use this to retrieve the task's name. If it hasn't been set (via set_toolname()) a default name is determined from the name of the executable file. The Fortran version is hdnameget().
  void set_toolversion(const char *)
  Use this to register a version number string for a task. The Fortran version is hdverset().
  void get_toolversion(char *)
  Use this to retrieve a string containing the task's version number. If it hasn't been set (via set_toolversion()) a default version number string of "0.0" is returned. The Fortran version is hdverget().
  void get_toolnamev(char *)
  Use this to retrieve a single string containing both the task's name and version number (joined by a "_"). The Fortran version is hdnamevget().
• headas_history.c
  Contains routines to get/set the value of the history parameter. Designed primarily for internal use and under normal circumstances should not be called by tasks explicitly.
  void get_history(int *)
  This routine returns the value of the history parameter (if present) or "-1" if unspecified. Called by headas_parstamp(). Fortran version is hdghis().
  void set_history(int)
  This registers the value of the history parameter. If it is called explicitly from a task it will override the user-specified value. Fortran version is hdphis().