Abort and Null

There are two special status values that can be returned by the parameter system when getting parameter values. They are PAR__ABORT and PAR__NULL, and are defined in the include file PAR_ERR.

6.1 Abort

PAR__ABORT is returned if a user enters !! in response to a prompt. In this event you should ensure that your application exits immediately. In practice this means that a) the user is not be prompted for any further parameters, though you do not have to check for an abort status after every PAR_GET call – the inherited status will look after that – and b) the application exits cleanly, freeing any resources used. There must be a status check before any of the parameter values are used, in case they have not been obtained successfully.

        INCLUDE ’PAR_ERR’       ! PAR error constants

            :       :       :

        CALL PAR_GET0I( ’STEP’, NSTEP, STATUS )
        CALL PAR_GET1R( ’HEIGHTS’, 50, HEITS, NUMHTS, STATUS )
        CALL PAR_GET0L( ’COLOUR’, COLOUR, STATUS )
        IF ( STATUS .EQ. PAR__ABORT ) THEN
           < perform any tidying operations >
           GOTO 999
        END IF

        < perform calculations >

    999 CONTINUE
        END

performs three parameter get calls, before testing for an abort; if an abort status is found, the routine exits. The status check against PAR__ABORT is unusual, and it is included to illustrate the symbolic constant. In normal circumstances you would test whether STATUS and SAI__OK were not equal, since it checks whether any error has occurred.

6.2 Null

PAR__NULL indicates that no value is available, and may be interpreted according to circumstances. This normally occurs when a user assigns a value of ! to a parameter.

Null can be used in a variety of circumstances. These include to end a loop, to indicate that an optional file is not required, and to force a default value to be used.

        CALL ERR_MARK
        CALL PAR_GET0R( ’WEIGHT’, WEIGHT, STATUS )
        IF ( STATUS .EQ. PAR__NULL ) THEN
           WEIGHT = 1.0
           CALL ERR_ANNUL( STATUS )
        END IF
        CALL ERR_RLSE

When the PAR_GET0R returns with the null status, the variable WEIGHT is set to 1.0. This particular instance has limited value, but the constant could be dynamic, depending on the values of other parameters or data read from files. The call to ERR_ANNUL restores STATUS to SAI__OK, and also removes an error message that would otherwise be reported later (usually when the application completes). Since we do not want to lose any earlier error reports, ERR_MARK and ERR_RLSE bracket this fragment of code to set up and release an error context. See SUN/104 for further details.

    100 CONTINUE
        CALL ERR_MARK
        CALL PAR_GET0I( ’NBINS’, NBIN, STATUS )
        IF ( STATUS .EQ. PAR__NULL ) THEN
           CALL ERR_ANNUL( STATUS )
           CALL ERR_RLSE
           GOTO 200
        END IF
        CALL ERR_RLSE

            < Perform calculations >

        GOTO 100

  *   Come here at the end of the calculations.
    200 CONTINUE

6 Abort and Null

6.1 Abort

6.2 Null