If the procedures recommended in this document have been adhered to, stand-alone applications which use the Message and Error Reporting Systems can be converted to run within the ADAM environment without change to the message and error reporting code. However, the use of the Message and Error Systems within ADAM applications provides access to facilities which cannot exist in the stand-alone version. This section describes these facilities and how they can be used. In what follows, a prior knowledge of ADAM applications programming to the level of SG/4 (ADAM – The Starlink Software Environment) is assumed.
In calls to the MSG output subroutines in ADAM applications, the message name is the name of an ADAM message parameter which can be associated with message text specified in the ADAM interface file instead of the text given in the subroutine argument. Message text specified in an interface file may include message tokens in the normal way.
If the message parameter is not specified in the interface file, the text given in the argument list is used.
Here is an example of using MSG_OUT within an ADAM application:
This statement will result in the message:
If the message parameter, ‘RD_TAPE’, is associated with a different text string in the interface module, e.g.
then the output message would be the one defined in the interface file, i.e.
This facility enables ADAM applications to conveniently support foreign languages. However, it is recommended that message parameters used in applications software are not normally defined in the interface file. If message parameters are defined in the interface file of an application, then it is clearly necessary to ensure that the text associated with each message parameter imparts essentially the same information as the text used within the program code, even if they are in different languages.
It is often necessary to refer to an ADAM program parameter in a message. There are two kinds of reference required:
Parameter references can be included in the text of a message by prefixing their names with the appropriate escape character. To include the keyword associated with a parameter, its name is prefixed with the percent escape character, “%”, e.g.
Here, the parameter ‘ET’ might be associated in the interface file with the keyword “EXPOSURE_TIME”, e.g.
In this case, the resultant output would be
To include the name of an object, device or file associated with a parameter, the parameter name is prefixed with the dollar escape character, “$”, e.g.
If the parameter ‘DATASET’ is associated with the object called “SWP1234” then this would produce the output
It is sometimes necessary to refer to a program parameter in a message, where its name is contained in a variable. In order to incorporate its reference into a message, a message token can be associated with its name. Here is an example of how this would be coded:
In this example, the escape sequence “^” prefixes the token name, ’PAR’. The sequence ’^PAR’ gets
replaced by the contents of the character string contained in the variable PNAME; this, being
prefixed by “%”, then gets replaced in the final message by the keyword associated with the
parameter.
The token name “STATUS” is reserved for use by the Error System and should not be used in Message System calls. It will never produce a useful message from an MSG subroutine.
In addition to the subroutine for setting the filter level for conditional message output, i.e. MSG_IFSET, the ADAM version of MSG also provides subroutine MSG_IFGET to get a character string from the parameter system and use this to set the filter level The subroutine has the calling sequence:
where PNAME is the parameter name. It is recommended that one parameter name is used universally for this purpose, namely MSG_FILTER, in order to clarify the interface file entries. The three acceptable strings for MSG_FILTER are:
MSG__QUIET;
MSG__NORM;
MSG__VERB.
MSG__DEBUG Abbreviations are accepted but any other value will result in an error report and STATUS being returned set to MSG__INVIF.
Graphical and textual output from an ADAM application can have problems with synchronisation. This is because the message output arrives at the terminal via the command process and is buffered, whereas the graphical output is sent directly to the terminal. The effect of this is that graphical output to the terminal can get corrupted by message output. This problem can be avoided by using the subroutine MSG_SYNC, which flushes the textual output buffer of the command process:
MSG_SYNC should be called immediately before any graphical output to avoid any corruption.
In calls to the subroutine ERR_REP in ADAM applications, the error name is the name of an ADAM message parameter which may be associated with message text specified in the interface file instead of the text supplied in the subroutine call. The system operates in the same way as for MSG (see §E.2.1).
In the non-ADAM, stand-alone, version of the Error System the initial error context level is set to one. Thus, before any calls to ERR_MARK have been made, calls to ERR_LEVEL will return a value of one and any error reports made at this level to be delivered immediately to the user. However, for ADAM applications, error reporting is deferred before the user’s application code is called. Thus calls to ERR_LEVEL made before any calls to ERR_MARK will return a value of two to the application,
Any remaining error reports are delivered to the user by the “fixed-part” of the ADAM application after execution of the user’s application code.
Historically, considerable use in ADAM was made of the VAX/VMS MESSAGE utility, both to generate globally unique error codes and to associate each error code with the text of an error message. The utility is also used by the VMS operating system for reporting its own messages. This has resulted in the idea of a reserved message token, STATUS, which would expand to the message associated with the given status value.
Every call to ERR_REP results in the status value given being converted into its associated VAX/VMS message, and then this message is associated with the token STATUS. Hence the global status may be used to construct an error message as follows:
This method of constructing error messages makes the assumption that all status values and operating system error numbers form part of a homogeneous set which can easily be associated with some appropriate message text. It is therefore not portable from VAX/VMS to other computer systems. If the STATUS token is used on other systems, an attempt will be made to translate it as a Starlink facility status value.
Subroutines following the recommended error reporting strategy outlined in §3.6 will always make an accompanying error report when the returned status is set to an error value. As a result, error reports based upon the reserved token STATUS are rarely necessary and limit the portability of ADAM software.
New code should not use the reserved token STATUS. If it is required to include the message associated with an error code in an error report, subroutine ERR_FACER should be used to create some other token.
ADAM applications are Fortran subroutines which are called by the software environment. An ADAM application has the schematic form
where the argument STATUS is given as SAI__OK. When the application ends and returns control to the environment, the final value of STATUS will reflect whether or not the application finished on an error condition. This provides the environment with a status to be associated with the application as a whole. The exit status of the application can be used by the environment to decide what to do next. If a status value other than SAI__OK is returned to the ADAM environment, then any pending error messages are output. Applications which fail should therefore return an error status. This recommendation does not, in fact, differ from that for any other subroutine obeying the inherited status strategy see §3.2).
The Message and Error Systems are intended for use when writing stand-alone and ADAM applications.
For ADAM system programming, where no assumptions may be made about the working order of either the ADAM parameter or data systems, another subroutine library, EMS (the Error Message Service) is available. The subroutine calling sequences for EMS are very similar to those of the Message and Error Systems (indeed many MSG and ERR routines are implemented as straight-through calls to EMS – hence the occurrence of EMS error messages from MSG or ERR routines). EMS is described in SSN/4. The Error Message Service library is intended specifically for use in ADAM system or general low level subroutine libraries. It should not be used in applications software.