Example skeleton applications

The lengthy subroutine list suggests that any application utilising AGI could end up looking complicated, but this need not be the case. By using the wrap-up routines simple applications need only call two or three routines from the list. As an example consider first an application that plots something on the screen and makes an entry in the database. A second application then uses a cursor to read a position from the graph. The second application is quite general and will work with any application that creates a DATA picture in the database, such as KAPPA:DISPLAY. Note that, as this example uses PGPLOT, it can be linked with either the GKS-based AGI library or the native-PGPLOT AGP library. However Starlink policy is that GKS is being phased out and so all new production applications should be linked with the AGP library as described here.

      SUBROUTINE PPLOT( STATUS )
      INCLUDE 'SAE_PAR'
      INTEGER I, ID1, ID2, N, STATUS
      PARAMETER ( N = 100 )
      REAL XP( N ), YP( N )

*   Check inherited global status
      IF ( STATUS .NE. SAI__OK ) GOTO 99

*   Define the function to plot
      DO I = 1, N
         XP( I ) = REAL( I )
         YP( I ) = REAL( I )
      ENDDO

*   Open AGI and PGPLOT through the ADAM interface
      CALL AGP_ASSOC( 'DEVICE', 'WRITE', ' ', .TRUE., ID1, STATUS )     ...1
      IF ( STATUS .NE. SAI__OK ) GOTO 99

*   Define the world coordinates of the viewport to match the data
      CALL PGSWIN( 0.0, 100.0, 0.0, 100.0 )

*   Create a box and plot the data
      CALL PGBOX( 'BCNST', 0.0, 0, 'BCNST', 0.0, 0 )
      CALL PGLINE( N, XP, YP )

*   Save the PGPLOT viewport as a picture in the database
      CALL AGP_SVIEW( 'DATA', 'PGLINE output', ID2, STATUS )            ...2

*   Close down AGI and PGPLOT cancelling the parameter
      CALL AGP_DEASS( 'DEVICE', .TRUE., STATUS )                        ...3

  99  CONTINUE
      END

The program requires an interface file to define the DEVICE parameter. The following example will do the job:-

interface PPLOT
   parameter DEVICE
      access 'READ'
      vpath 'PROMPT'
      prompt 'Display device '
   endparameter
endinterface

Program notes:

1.

The routine AGP_ASSOC is used to access the database and open PGPLOT. It is a wrap-up routine for a number of commonly called AGI functions. The mode is set to 'WRITE' so that the plotting area is cleared and the border argument is set true to allow room for annotation of the axes. Passing an empty string in the name argument results in the current database picture being used to define the PGPLOT viewport.

2.

The current PGPLOT viewport is saved as an AGI picture in the database.

3.

The database and PGPLOT are closed using another of the wrap-up routines. This also tidies up any picture identifiers returned from AGI routines, and in this example cancels the parameter association.

      SUBROUTINE PCURS( STATUS )
      INCLUDE 'SAE_PAR'
      INTEGER ID, STATUS
      CHARACTER CH, TEXT*64
      REAL XC, YC

*   Check inherited global status
      IF ( STATUS .NE. SAI__OK ) GOTO 99

*   Open AGI and PGPLOT through the ADAM interface
      CALL AGP_ASSOC( 'DEVICE', 'READ', 'DATA', .FALSE., ID, STATUS )   ...4
      IF ( STATUS .NE. SAI__OK ) GOTO 99

*   Request a PGPLOT cursor
      CALL PGCURSE( XC, YC, CH )

*   Report the result
      WRITE( TEXT, '( ''Cursor position ='', 2F6.1 )' ) XC, YC
      CALL MSG_OUT( 'PCURS', TEXT, STATUS )

*   Close down AGI and PGPLOT cancelling the parameter
      CALL AGP_DEASS( 'DEVICE', .TRUE., STATUS )                        ...5

  99  CONTINUE
      END

Program notes:

4.

The mode argument in AGP_ASSOC is set to 'READ' to ensure that the plot is not cleared. The name argument specifies that the last picture of type DATA should be recalled. The border argument is set false to ensure that the PGPLOT viewport is created to exactly match the DATA picture.

5.

The call to AGI_END within AGP_DEASS resets the current picture to be the one current when the application began.