Reporting messages

The primary message reporting subroutine is msgOut. It has a calling sequence of the form:

      msgOut( param, text, status );

      CALL MSG_OUT( PARAM, TEXT, STATUS )

where the argument param is a character string giving the name of the message, text is a character string giving the message text, and status is the integer subroutine status value (a pointer to an int in C). msgOut sends the message string, text, to the standard output stream which will normally be the user's terminal.

The subroutine msgOut uses the Starlink convention of inherited status. This means that calls to msgOut will not output the message unless the given value of status is equal to SAI__OK. If an error is encountered within the subroutine, then status is returned set to an error value. (The global constant SAI__OK is defined in the include file sae_par.h (SAE_PAR for Fortran). )

The maximum length for an output message is 300 characters. If it exceeds this length, then the message is truncated with an ellipsis, i.e. ``...'', but no error will result.

By default, messages are split so that output lines do not exceed 79 characters - the split is made on word boundaries if possible. The maximum output line size can be altered using tuning parameters.

It is recommended that, within the application, the message name, param, should be a unique identifier for the message string, text. However, the message name serves no useful purpose within a stand-alone application and is often given as a blank string. In ADAM applications the message name has a specific purpose.

Here is an example of using msgOut:

      msgOut( "EXAMPLE_MSGOUT", "An example of msgOut", status );

      CALL MSG_OUT( 'EXAMPLE_MSGOUT', 'An example of MSG_OUT.', STATUS )

It is sometimes useful to intersperse blank lines amongst lines of textual output for clarity. This could be done using calls to msgOut, e.g.

      msgOut( "MSG_BLANK", "", status );

      CALL MSG_OUT( 'MSG_BLANK', ' ', STATUS )

For convenience, the subroutine msgBlank has been provided for this purpose, e.g.

      msgBlank( status );

      CALL MSG_BLANK( STATUS )

The status argument in msgBlank behaves in the same way as the status argument in msgOut.