STATUS and error handling

Most ADAM subroutines have an integer parameter called STATUS. STATUS has a success value (SAI__OK) which each routine will return if it completes successfully. If the routine fails for some reason it will return an error code indicating the nature of the error. An ADAM A-task routine (such as SQUARE) will be called with a STATUS of SAI__OK. If it returns a bad status value to its caller this will result in an appropriate message being output.

There is a further important feature of the status convention. If an ADAM routine is called with its STATUS argument having an error value on input, then the routine will do nothing and will return immediately. This feature means that it is usually not necessary to check STATUS after each routine is called. A series of ADAM routines can be called with the STATUS being passed from one to the next. If an error occurs in one of them, the subsequent routines will do nothing and the final status will indicate the error code from the routine that failed. If this STATUS value is then returned by the A-task main routine to its caller an error message will result. Thus the error will be correctly processed with no special code being added to check for errors.

It is important, however, to take care that code that does not consist of calls to ADAM routines does not get executed after an error has occurred. For this reason our SQUARE example would be better written as:

      SUBROUTINE SQUARE(STATUS)
      INTEGER STATUS
      INCLUDE 'SAE_PAR'  ! This provides the ADAM status codes
      REAL R,RR
      CALL PAR_GET0R('VALUE',R,STATUS)                        
      IF (STATUS .EQ. SAI__OK) THEN
         RR = R*R           
         CALL MSG_SETR('RVAL',R)
         CALL MSG_SETR('RSQUARED',RR)
         CALL MSG_OUT(' ','The Square of ^RVAL is ^RSQUARED',STATUS)
      ENDIF
      END

This ensures that if the STATUS from PAR_GET0R is bad the rest of the routine is not executed with an undefined value of R. It is actually not necessary to include MSG_OUT in the IF block as this would not execute if STATUS was bad.

More sophisticated error handling can be provided by using routines in the ERR_ package. These facilities are fully described in SUN/104.