Three subroutines exist to enable a message token to be built from the error code returned under these circumstances. These subroutines are:
where STATUS is a standard Starlink facility status value,ERR_FACER( TOKEN, STATUS )
where IOSTAT is a Fortran I/O status code, andERR_FIOER( TOKEN, IOSTAT )
where SYSTAT is a status value returned from an operating system routine.ERR_SYSER( TOKEN, SYSTAT )
Each of the above routines will assign the message associated with the given error code to the specified token, appending the message if the token is already defined. The error code argument is never altered by these routines. It is important that the correct routine is called, otherwise the wrong message or, at best, only an error number will be obtained.
ERR_FACER is not likely to be useful for applications programmers because suitable error reports will probably have been made by higher-level facilities called directly by the application - it is really provided for completeness. The other two routines will be more useful.
Here is an example of using ERR_FIOER. It is a section of code that writes a character variable to a formatted sequential file, given the Fortran logical unit of the file:
* Write the character variable STR. WRITE( UNIT, '(A)', IOSTAT = IOSTAT ) STR * Check the Fortran I/O status. IF ( IOSTAT .NE. 0 ) THEN * Fortran write error, so set STATUS. STATUS = SAI__ERROR * Define the I/O status and logical unit message tokens and attempt * to obtain the file name. CALL ERR_FIOER( 'MESSAGE', IOSTAT ) CALL MSG_SETI( 'UNIT', UNIT ) INQUIRE( UNIT, NAME = FNAME, IOSTAT = IOS ) * Check the returned I/O status from the INQUIRE statement and act. IF ( IOS .EQ. 0 ) THEN * Define the file name message token. CALL MSG_SETC( 'FNAME', FNAME ) * Report the error. CALL ERR_REP( 'PUTSTR_WRERR', : 'Error writing to file ^FNAME on ' // : 'unit ^UNIT: ^MESSAGE', STATUS ) ELSE * No file name has been found so just report the error. CALL ERR_REP( 'PUTSTR_WRERR', : 'Error writing to unit ^UNIT: ^MESSAGE', STATUS ) END IF GO TO 999 END IF ... 999 CONTINUE END
Here, the name of the file being read is also obtained in order to construct a comprehensive error message, which might be something like:
!! Error writing to file BLOGGS.DAT on unit 17: Disk quota exceeded.
Note that the I/O status values used in Fortran do not have universally defined meanings except for zero (meaning no error), but by using ERR_FIOER it is still possible to make high quality error reports about Fortran I/O errors in a portable manner.
In a similar way, the subroutine ERR_SYSER may be used to assign an operating system message associated with the system status flag SYSTAT to the named message token. Of course, software that calls operating system routines directly cannot be portable, but ERR_SYSER provides a convenient interface for reporting errors that occur in such routines in a form that can be easily changed if necessary. For example:
IF ( <system error condition> ) THEN * Operating system error, so set STATUS. STATUS = SAI__ERROR * Report the error and abort. CALL ERR_SYSER( 'ERRMSG', SYSTAT ) CALL ERR_REP( 'ROUTN_SYSER', 'System error: ^ERRMSG', STATUS ) GO TO 999 END IF ... 999 CONTINUE END
Fortran I/O and operating system error messages, obtained through calls to ERR_FIOER and ERR_SYSER respectively, will differ depending upon which operating system (or even flavour of operating system) an application is run on.
Because of the necessary generality of these messages (and those from ERR_FACER), many will appear rather vague and unhelpful without additional contextual information. This is particularly true of UNIX implementations. It is very important to provide additional contextual information when using these routines in order to avoid obfuscating rather than clarifying the nature of an error. This can be done either as part of the error message which includes the message token set by ERR_FACER, ERR_FIOER or ERR_SYSER, or by making a further error report. The examples in this section provide a good illustration of how this can be done.
MERS (MSG and ERR) Message and Error Reporting Systems