Begin-End blocks

As the database is not closed until all identifiers have been annulled it is important that each task keeps its allocation of identifiers under control. For a complicated application annulling individual identifiers may be tiresome and so a general tidying up scheme is available using a begin-end block. The routines AGI_BEGIN and AGI_END are used to bracket a block of code and all the identifiers allocated within the block are automatically annulled by AGI_END. These routines may be nested, (up to a depth of eight) but each AGI_BEGIN must have its corresponding AGI_END.

As well as annulling identifiers the routine AGI_END performs another important function. The routine takes a picture identifier as its input and this picture is made current. If the identifier is valid then this is no different to calling AGI_SELP, but if the argument passed to AGI_END is a negative number then the picture that was current when the corresponding AGI_BEGIN was called is made current again. This is useful for applications that need to restore the current picture to that which was current when the application began.

The following two examples show different uses of a begin-end block. In the first example the call to AGI_END annuls all the identifiers, which results in the database being closed, since there are no more active identifiers. As there was no current picture when the corresponding AGI_BEGIN was called (since the database had not been opened) the negative argument in AGI_END has no effect in this case, and the picture that was current just before the call to AGI_END remains current.

    *   Begin an AGI scope
          CALL AGI_BEGIN

    *   Open AGI on a device obtained from the parameter system
          CALL AGI_ASSOC( 'DEVICE', 'WRITE', ID, STATUS )

    *   Main body of program
          <main body of program>

    *   Annul identifiers and close the database
          CALL AGI_END( -1, STATUS )

In the second example AGI_BEGIN is put after AGI_ASSOC. When AGI_END is called the identifier returned from AGI_ASSOC is not annulled, since it is outside the scope of the begin-end block. The negative argument in AGI_END makes the picture that was current when the corresponding AGI_BEGIN was called current again (in this example the picture that was current when the application began).

    *   Open AGI on a device obtained from the parameter system
          CALL AGI_ASSOC( 'DEVICE', 'WRITE', ID, STATUS )

    *   Begin an AGI scope
          CALL AGI_BEGIN

    *   Main body of program
          <main body of program>

    *   Annul identifiers from the main body of the program
    *   and reinstate the current picture
          CALL AGI_END( -1, STATUS )

    *   Annul the initial identifier and close the database
          CALL AGI_ANNUL( ID, STATUS )