C Using EMS within ADAM system software

 C.1 Overview
 C.2 Message parameters
 C.3 Parameter references
 C.4 Reserved tokens
 C.5 Synchronising message output
 C.6 Routines specific to the ADAM fixed part

C.1 Overview

This document has so far discussed the use of EMS in a general context. In this section, specific differences between EMS and the ADAM versions of the Message and Error Reporting Systems, MSG and ERR, are presented.

C.2 Message parameters

In calls to the ADAM version of ERR_REP, the error message name PARAM is a globally unique identifier for the error message text which corresponds to the message parameter of the error message. The ADAM interface file can be used to associate this message parameter with an error message, and only if this message parameter is not defined in the interface file is the argument TEXT used in the error report. When using EMS_REP (or the deprecated EMS_MLOAD) within the ADAM environment software, no access to the ADAM interface file exists and so the error message given by the argument TEXT is always used. The use of a globally unique error message name is still recommended for reported error messages to uniquely identify the error message text to the programmer, using the convention outlined in SUN/104.

C.3 Parameter references

The ADAM versions of MSG and ERR allow reference to ADAM program parameters within the message text. Reference can be made either to parameter-keyword associations or to the name of an ADAM data system object, data file or device associated with a parameter. In message text used in calls to MSG and ERR routines these parameter associations are indicated by the percent, “%”, and dollar, “$”, escape characters respectively. EMS does not have access to the ADAM parameter system and so cannot refer to ADAM parameters in the text of messages. The escape characters “%” and “$” are therefore treated literally as part of the message text in calls to EMS_REP and EMS_EXPND (or the deprecated EMS_MLOAD), as they are in the stand-alone versions of MSG and ERR.

C.4 Reserved tokens

In the ADAM versions of MSG and ERR a reserved token, ‘STATUS’, can be used to insert the message associated with a status value. In EMS, as in the stand-alone versions of MSG and ERR, there are no reserved message tokens

C.5 Synchronising message output

Because there is no callable mechanism provided by EMS to deliver messages to the user, no message synchronising mechanism is provided by EMS.

C.6 Routines specific to the ADAM fixed part

There are three ERR routines which start up, clear and stop the Error Reporting System within the ADAM fixed part to ensure that the delivery of any reported error messages is deferred and that any messages pending output are delivered to the user when the application has finished. These subroutines are ERR_START, ERR_CLEAR and ERR_STOP – they are discussed in this document because they are purely for system programming and will affect the use of EMS as well as ERR within ADAM.

ERR_START has the effect of marking a new EMS context and thus deferring the delivery of any reported error messages to the user. The new context is known as the default context.

ERR_CLEAR has the effect of returning the current error context to the ‘default’ level set by ERR_START and flushing any reported error messages to the user. Thus, the effect of any mismatched ‘mark’ and ‘release’ calls within an application is annulled.

ERR_STOP clears the error message table by calling ERR_CLEAR and then returns the error reporting context to the initial context level, i.e. the level prior to the call to ERR_START.

The use of these three routines is entirely reserved for starting up, clearing and stopping error reporting within the environment, e.g. the ADAM fixed part, and must not be used for any other purpose.

These routines exist only in the ADAM version of the ERR library and are linked using the procedure given in SUN/104.