next up previous 211
Next: Reporting errors
Up: ERR - Error Reporting System
Previous: Inherited status checking


Setting and defining status values

The use of the global constants SAI__OK and SAI__ERROR for setting status values is recommended in general applications. These global constants may be defined in each subroutine by including the file SAE_PAR at the beginning of the subroutine, prior to the declaration of any subroutine arguments or local variables. When writing subroutine libraries, however, it is useful to have a larger number of globally unique error codes available and to define symbolic constants for these in a separate include file. The naming convention:

fac__ecode

should be used for the names of error codes defined in this way; where fac is the three-character facility prefix and ecode is up to five alphanumeric characters of error code name. Note the double underscore used in this naming convention. The include file should be referred to by the name fac_ERR, e.g.

      INCLUDE 'SGS_ERR'

where the facility name is SGS, the Starlink Simple Graphics System, in this case. These symbolic constants should be defined at the beginning of every subroutine which requires them, prior to the declaration of any subroutine arguments or local variables.

The purpose of error codes is to enable the status argument to indicate that an error has occurred by having a value which is not equal to SAI__OK. By using a set of predefined error codes the calling module is able to test the returned status to distinguish between error conditions which may require different action. It is not generally necessary to define a very large number of error codes which would allow a unique value to be used every time an error report is made. It is sufficient to be able to distinguish the important classes of error which may occur. Examples of existing software can be consulted as a guide in this matter.

The Starlink utility MESSGEN should be used on UNIX to generate a set of globally unique error codes for a package. It may be used to create the Fortran include file and/or a C header file defining symbolic names for the error codes, and/or the ``facility error message file'', which can be used to associate a simple message with each error code. There is an alternative but compatible method of calculating the set of error codes for a package.

Software from outside a package which defines a set of error codes may use that package's codes to test for specific error conditions arising within that package. However, with the exception of the SAI__ codes, it should not assign these values to the status argument. To do so could cause confusion about which package detected the error.



next up previous 211
Next: Reporting errors
Up: ERR - Error Reporting System
Previous: Inherited status checking

MERS (MSG and ERR) Message and Error Reporting Systems
Starlink User Note 104
P C T Rees
A J Chipperfield
22 October 2001
E-mail:ussc@star.rl.ac.uk

Copyright © 2001 Council for the Central Laboratory of the Research Councils