5 Error Handling

The PGPLOT, SGS and GKS parameter routines conform to the Starlink error reporting and inherited status strategy described in SUN/104. Error reports will generally be of the form:

  ROUTINE_NAME: Text

but where there routine name is not useful, it will be omitted.

If it is required to test for particular status values, symbolic names should be used. They can be defined by including in the application, the statements:

  INCLUDE ’SAE_PAR’   ! To define SAI__OK etc.
  INCLUDE ’SGS_ERR’   ! To define the SGS__ error values

for SGS program, or the statements:

  INCLUDE ’SAE_PAR’   ! To define SAI__OK etc.
  INCLUDE ’PGP_ERR’   ! To define the GKS__ error values

for PGPLOT programs

  INCLUDE ’SAE_PAR’   ! To define SAI__OK etc.
  INCLUDE ’GKS_ERR’   ! To define the GKS__ error values

for GKS programs. It is of course possible to include PGPLOT, SGS and GKS status values in a single program.

The symbolic names are listed in Section 7.

A substitute GKS error handling routine is linked with ADAM applications so that error messages are reported in conformance with the Starlink error reporting strategy, however, GKS stand-alone routines do not operate the inherited status strategy. Thus programs which use GKS must be very careful about handling error conditions if they are to avoid generating streams of unhelpful error messages.

Subroutine GKS_GSTAT has been provided by the environment to help with this problem. If this routine is called after every non-environment GKS routine (or sequence of routine calls) then the net effect is as if the GKS routine(s) did have an inherited status argument.

Note that for stand alone GKS routines which do have a status argument, the environment status variable should not be used. Use a local variable, ignore its value and use GKS_GSTAT to get an environment status value for the routine. Liberal use of IF .. THEN .. ELSE .. ENDIF structures testing the environment status value is recommended to prevent invalid output from GKS and a large number of error messages.

Note also that the GKS enquiry routines do not report an error when they fail, they just return a status value (this is to allow the GKS error handling routine to make enquires about the state of GKS when handling an error without fear of triggering another error report and hence being called recursively). This means that an application that detects an error from an enquiry routine must compose and report a suitable message as well as setting the ADAM status

Example :

  
        SUBROUTINE GKSTEST(STATUS)
  
  * Test GKS in ADAM.
  * Draw a box and write some text in the box.
  
        INCLUDE ’SAE_PAR’
        INCLUDE ’GKS_PAR’
        INTEGER STATUS
        INTEGER WKID
        INTEGER N
        PARAMETER (N = 5)
        REAL X(N), Y(N)
        DATA X/0.0,0.0,1.0,1.0,0.0/,
       :     Y/0.0,1.0,1.0,0.0,0.0/
  
  * Check STATUS on entry.
        IF ( STATUS .NE. SAI__OK ) RETURN
  
  * Open GKS, open and activate workstation.
        CALL GKS_ASSOC( ’DEVICE’, ’WRITE’, WKID, STATUS )
        IF ( STATUS .EQ. SAI__OK ) THEN
  * End of standard opening sequence.
  *---------------------------------------------------------------------
  * Draw a box and write in it.
  *   Polyline.
           CALL GPL( N, X, Y )
  *   Set text alignment.
           CALL GSTXAL( GACENT, GACENT )
  *   Set character height.
           CALL GSCHH( 0.04 )
  *   Text.
           CALL GTX( 0.5, 0.5, ’Successful test of GKS 7.2’ )
  *---------------------------------------------------------------------
  * Check for error in GKS call sequence.
           CALL GKS_GSTAT( STATUS )
  
  * Cancel parameter and annul the workstation id.
           CALL GKS_CANCL( ’DEVICE’, STATUS )
        ENDIF
  
        CALL GKS_DEACT( STATUS )
        END

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