Interface to SGS - (AGI library only)

A set of routines are supplied to interface the database to the SGS graphics package, these are prefixed by AGS_ instead of AGI_. A picture in the database is equated with an SGS zone. SGS is activated with a call to AGS_ACTIV. This does not open a device for plotting. A device is opened when the first call to AGS_NZONE is made. The actual device that is opened will be the one associated with the current picture in the database. This means that AGI has to be open before AGS_NZONE can be called. AGS_NZONE creates an SGS zone from the current AGI picture, and returns the zone identifier. An SGS zone is saved as a picture in the database using a call to AGS_SZONE. The size of the new picture must be less than or equal to the size of the current picture in the database otherwise and error status is returned. SGS is shut down using AGS_DEACT.

The job of opening and closing the device is handled by the AGS_ routines and therefore the routines SGS_ASSOC and SGS_CANCL or SGS_OPEN and SGS_CLOSE should not be called when using the AGS_ routines.

The first example shows how an application might save an SGS zone in the database.

    *   Obtain the device name from the ADAM parameter system
          CALL AGI_ASSOC( 'DEVICE', 'WRITE', ID1, STATUS )
          CALL AGI_BEGIN

    *   Open the given device for plotting
          CALL AGS_ACTIV( STATUS )
          CALL AGS_NZONE( IZONE, STATUS )

    *   Plot the data in an SGS zone
          <plot the data with SGS>

    *   Save the current zone as a picture in the database
          CALL AGS_SZONE( 'DATA', 'Description', ID2, STATUS )

    *   Close down
          CALL AGS_DEACT( STATUS )
          CALL AGI_END( -1, STATUS )
          CALL AGI_CANCL( 'DEVICE', STATUS )

The second example shows how another application could recreate a zone, perhaps to overlay one plot with another, or to obtain coordinates with a cursor. It assumes that the current picture in the database is the one that is wanted. If this is not the case the recall routines can be used to search the database for the correct picture.

    *   Obtain the device name from the ADAM parameter system
    *   Use update mode to ensure the original plot is not cleared
          CALL AGI_ASSOC( 'DEVICE', 'UPDATE', ID1, STATUS )
          CALL AGI_BEGIN

    *   Open the given device for plotting recreating the current
    *   picture as an SGS zone
          CALL AGS_ACTIV( STATUS )
          CALL AGS_NZONE( IZONE, STATUS )

    *   Plot with SGS
          <plot with SGS>

    *   Close down
          CALL AGS_DEACT( STATUS )
          CALL AGI_END( -1, STATUS )
          CALL AGI_CANCL( 'DEVICE', STATUS )

These examples show that the AGI operations of accessing the database and opening the graphics package are common to both applications. These common opening and closing operations have been packaged up into single routines. Thus the sequence of calls AGI_ASSOC, AGI_BEGIN, AGS_ACTIV, AGS_NZONE can be replaced by a single call to AGS_ASSOC, and the sequence of calls AGS_DEACT, AGI_END, AGI_CANCL can be replaced by a single call to AGS_DEASS. Note that these wrap-up routines only exist for the ADAM interface. If the application is using the non-ADAM routines AGI_OPEN and AGI_CLOSE then the sequence of calls has to be made explicitly. Using these wrap-up routines then second application above would become

    *   Obtain the device name from the ADAM parameter system and open
    *   SGS on the given device
          CALL AGS_ASSOC( 'DEVICE', 'UPDATE', ' ', ID1, IZONE, STATUS )

    *   Plot with SGS
          <plot with SGS>

    *   Close down
          CALL AGS_DEASS( 'DEVICE', .TRUE., STATUS )

The third (picture name) argument in AGS_ASSOC can optionally be used to recall the last picture of the given name using AGI_RCL. If the name string is blank (as in the example above) then this recall routine is not called and the current database picture is returned. If the second argument in AGS_DEASS is false then the ADAM parameter is not cancelled and instead the picture identifier returned from AGS_ASSOC is annulled.

If GKS calls are mixed in with the SGS calls to produce the plot then some GKS operations may result in the plot being cleared when the device is shut down. This can happen if the device is opened with 'WRITE' mode, which results in the zone being initially cleared, and then some aspect of the device, such as a pen colour, is changed using GKS calls. GKS believes that the original plot is now wrong because the colours are wrong and requests that the plot be redrawn in the new colours. By default this request does not happen immediately but is deferred until closedown. An application can force the update to happen immediately by setting the deferral mode:

    *   Set the GKS deferral mode to 'ASAP'
          CALL SGS_ICURW( IWKID )
          CALL GSDS( IWKID, 0, 1 )