The subroutine used to report errors is ERR_REP. It has a calling sequence of the form
CALL ERR_REP( PARAM, TEXT, STATUS )
Here, the argument PARAM is the error message name, TEXT is the error message text and STATUS is the inherited status. These arguments are broadly similar to those used in the Message System subroutine MSG_OUT.
The error message name PARAM should be a globally unique identifier for the error report. It is recommended that it has the form:
routn_message
in the general case of subroutines within an application, or:
fac_routn_message
in the case of routines within a subroutine library. In the former case, routn is the name of the application routine from which ERR_REP is being called and message is a sequence of characters uniquely identifying the error report within that subroutine. In the latter case, fac_routn is the full name of the subroutine from which ERR_REP is being called (see the Starlink Application Programming Standard for a discussion of the recommended subroutine naming convention), and message is a sequence of characters unique within that subroutine. These naming conventions are designed to ensure that each individual error report made within a complete software system has a unique error name associated with it.
Here is a simple example of error reporting where part of the application code of the previous example detects an invalid value of some kind, sets STATUS, reports the error and then aborts:
IF ( <value invalid> ) THEN STATUS = SAI__ERROR CALL ERR_REP( 'ROUTN_BADV', 'Value is invalid.', STATUS ) GO TO 999 END IF ... 999 CONTINUE END
In the event of an invalid value, the Error System would produce a message like:
!! Value is invalid.Note that when the message is output to the user, the Error System precedes the given text with exclamation marks.
The sequence of three operations:
- 1.
- Set STATUS to an error value.
- 2.
- Report an error.
- 3.
- Abort.
is the standard response to an error condition and should be adopted by all software which uses the Error System.
Note that the behaviour of the STATUS argument in ERR_REP differs somewhat from that in MSG_OUT in that ERR_REP will execute regardless of the input value of STATUS. Although the Starlink convention is for subroutines not to execute if their status argument indicates a previous error, the Error System subroutines obviously cannot behave in this way if their purpose is to report these errors.
On exit from ERR_REP the value of STATUS remains unchanged, with three exceptions:
MERS (MSG and ERR) Message and Error Reporting Systems