### 7 Intercepting Messages

Although there is no callable provision for message output directly from EMS, the output of messages at this level in the ADAM subroutine hierarchy is still possible. It can be done by intercepting any pending error messages within the current error context (or informational messages) using subroutines EMS_ELOAD or EMS_EXPND, which return the message in a character variable, and then using a private package-related mechanism to output the message. Here, the mechanism used to output the message, e.g. to a log file, and its resilience to failure must be the responsibility of the subroutine library calling EMS. The use of private package equivalents to MSG_OUT or ERR_FLUSH must be fully justified and the justification presented in the documentation for the subroutine library concerned.

EMS_ELOAD returns error message pending in the current error context, one by one in a series of calls; it has the calling sequence:

CALL EMS_ELOAD( PARAM, PARLEN, OPSTR, OPLEN, STATUS )

On the first call of this routine, the error table for the current context is copied into a holding area, the current error context is annulled and the first message in the holding area is returned. Thereafter, each time the routine is called, the next message from the holding area is returned. The argument PARAM is the returned message name and PARLEN the length of the message name in PARAM. OPSTR is the returned error message text and OPLEN is the length of the error message in OPSTR.

The status associated with the returned message is returned in STATUS until there are no more messages to return – then STATUS is set to SAI__OK, PARAM and OPSTR are set to blanks and PARLEN and OPLEN to 1. If there are no messages pending on the first call, a warning message is returned with STATUS set to EMS__NOMSG.

After STATUS has been returned SAI__OK, the whole process is repeated for subsequent calls. This process is the same as for ERR_LOAD (see SUN/104) which just calls EMS_ELOAD.

EMS_EXPND has the calling sequence:

CALL EMS_EXPND( TEXT, OPSTR, OPLEN, STATUS )

TEXT is the message text, OPSTR is the returned message text, OPLEN is the length of the message in OPSTR and STATUS is the inherited status.

The behaviour of EMS_EXPND is to expand any message tokens in the message text and return the expanded message through the character variable OPSTR.

For both EMS_EXPND and EMS_ELOAD, if the message text is longer than the declared length of OPSTR then the message is truncated with an ellipsis, i.e. “…”, but no error results.

The symbolic constants EMS__SZPAR and EMS__SZMSG are provided for declaring the lengths of character variables which are to receive message names and error messages in this way. These constants are defined in the include file EMS_PAR (see Appendix E).