The heautils library contains the HEADAS error handling functions, which provide a means by which calling code can set and clear error conditions, as well as manage supporting information about errors. When an error condition is first encountered, a call to the HDerror_throw function sets the error state of the error handler, and adds an optional message. Subsequent calls to the HDerror_hint function can be used to place additional messages on the error stack. Each of these can produce an error message containing the file name and line number where the error occurred. When used, this feature in effect provides a stack trace of the error, but without using a debugger. The HDerror_reset function can be used to reset the error handler to a non-error condition. In this case, the stack is erased, and no error code is retained by the stack.
In addition, the HEADAS error facility provides a means of establishing default error messages for error codes. Several error ranges already exist within HEADAS. For example, error numbers between 1 and 999 are associated with CFITSIO errors, while -3999 to -3000 are associated with APE. Each of these error codes has an associated standard error message. The HEADAS error handler contains a map of each error code to its message. Also there is a means to add new error maps, in order to provide standard error messsages for new software components within different numeric code ranges. These maps may be used as a task exits to print the standard message if no custom message is available.
For convenience, several macros which wrap these functions are also provided. The macros HD_ERR_SET, HD_ERR_THROW, and HD_ERR_HINT use the functions HDerror_throw and HDerror_hint to do their work. There were two reasons for defining these macros. One is that the macros can check their status arguments before calling their underlying functions, thus eliminating the overhead of a function call unless an error actually occurs. The second is that the functions HDerror_throw and HDerror_hint have arguments which can be used to give the location (source file and line number) of the error. The macros listed above do not take these arguments, but use the __FILE__ and __LINE__ macros to create them when they call the appropriate error function.