next up previous 211
Next: Deferred error reporting
Up: ERR - Error Reporting System
Previous: The content of error messages


Adding contextual information

Instead of simply aborting when a status value is set by a called subroutine, it is also possible for an application to add further information about the circumstances surrounding the error. In the following example, an application makes several calls to a subroutine which might return an error status value. In each case, it reports a further error message so that it is clear which operation was being performed when the lower-level error occurred:

*  Smooth the sky values.
      CALL SMOOTH( NX, NY, SKY, STATUS )
      IF ( STATUS .NE. SAI__OK ) THEN
         CALL ERR_REP( 'SKYOFF_SKY',
     :                'SKYOFF: Failed to smooth sky values.', STATUS )
         GO TO 999
      END IF

*  Smooth the object values.
      CALL SMOOTH( NX, NY, OBJECT, STATUS )
      IF ( STATUS .NE. SAI__OK ) THEN
         CALL ERR_REP( 'SKYOFF_OBJ',
     :                'SKYOFF: Failed to smooth object values.', 
     :                STATUS )
         GO TO 999
      END IF

      ...

999   CONTINUE
      END

Notice how an additional error report is made in each case, but because the original status value contains information about the precise nature of the error which occurred within the subroutine SMOOTH, it is left unchanged.

If the first call to subroutine SMOOTH were to fail, say because it could not find any valid pixels in the image it was smoothing, then the error message the user would receive might be:

!! Image contains no valid pixels to smooth.
!  SKYOFF: Error smoothing sky image.

The first part of this message originates from within the subroutine SMOOTH, while the second part qualifies the earlier report, making it clear how the error has arisen. Since SKYOFF is the name of an application known to the user, it has been included in the contextual error message.

This technique can often be very useful in simplifying error diagnosis, but it should not be overdone; the practice of reporting errors at every level in a program hierarchy tends to produce a flood of redundant messages. As an example of good practice for a subroutine library, an error report made when an error is first detected, followed by a further contextual error report from the ``top-level'' routine which the user actually called, normally suffices to produce very helpful error messages.



next up previous 211
Next: Deferred error reporting
Up: ERR - Error Reporting System
Previous: The content of error messages

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