Diagnostic output and other text messages must be able to be separated from the standard output stream to enable, e.g., 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(), e.g. via an internal write.
Future GUI development and/or other enhancements to HEASOFT 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 old FTOOLS fcerr() routine). As with hdecho(), the output error message must be constructed internally prior to calling hderr().