3 Summary of AGI Calls

3.1 Interface to PGPLOT (both libraries)

AGP_ACTIV( status )
    Initialise PGPLOT

AGP_ASSOC( param, acmode, pname, border, picid, status)
    Associate a device with AGI and PGPLOT through ADAM

AGP_DEACT( status )
    Close down PGPLOT

AGP_DEASS( param, parcan, status )
    De-associate a device from AGI and PGPLOT

AGP_NVIEW( border, status )
    Create a new PGPLOT viewport from the current picture

AGP_SVIEW( pname, coment, picid, status )
    Save the current PGPLOT viewport in the database

3.2 Interface to SGS (only in AGI library)

AGS_ACTIV( status )
    Initialise SGS

AGS_ASSOC( param, acmode, pname, picid, newzon, status )
    Associate a device with AGI and SGS through ADAM

AGS_DEACT( status )
    Close down SGS

AGS_DEASS( param, parcan, status )
    De-associate a device from AGI and SGS

AGS_NZONE( newzon, status )
    Create a new SGS zone from the current picture

AGS_SZONE( pname, coment, picid, status )
    Save the current SGS zone in the database

3.3 Interface to IDI (only in AGI library)

AGD_ACTIV( status )
    Initialise IDI

AGD_ASSOC( param, acmode, pname, memid, picid, dispid, xsize, ysize, xoff, yoff, status )
    Associate a device with AGI and IDI through ADAM

AGD_DEACT( status )
    Close down IDI

AGD_DEASS( param, parcan, status )
    Deassociate a device from AGI and IDI

AGD_NWIND( memid, dispid, xsize, ysize, xoff, yoff, status )
    Define an IDI window from the current picture

AGD_SWIND( dispid, memid, xsize, ysize, xoff, yoff, pname, coment, wx1, wx2, wy1, wy2, picid, status )
    Save an IDI window in the database

3.4 Control (both libraries)

AGI_ANNUL( picid, status )
    Annul a picture identifier

AGI_ASSOC( param, acmode, picid, status )
    Associate an AGI device with an ADAM parameter

AGI_BEGIN
    Mark the beginning of a new AGI scope

AGI_CANCL( param, status )
    Cancel the ADAM device parameter

AGI_CLOSE( status )
    Close AGI in non-ADAM environments

AGI_END( picid, status )
    Mark the end of an AGI scope

AGI_NUPIC( wx1, wx2, wy1, wy2, pname, coment, newx1, newx2, newy1, newy2, picid, status )
    Create a new picture in the database

AGI_OPEN( wkname, acmode, picid, status )
    Open an AGI device in a non-ADAM environment

AGI_PDEL( status )
    Delete all the pictures on the current device

AGI_SELP( picid, status )
    Select the given picture as the current one

AGI_SROOT( status )
    Select the root picture for searching

3.5 Recall (both libraries)

AGI_RCF( pname, picid, status )
    Recall first picture of specified name

AGI_RCFP( pname, x, y, picid, status )
    Recall first picture embracing a position

AGI_RCL( pname, picid, status )
    Recall last picture of specified name

AGI_RCLP( pname, x, y, picid, status )
    Recall last picture embracing a position

AGI_RCP( pname, pstart, picid, status )
    Recall preceding picture of specified name

AGI_RCPP( pname, pstart, x, y, picid, status )
    Recall preceding picture embracing a position

AGI_RCS( pname, pstart, picid, status )
    Recall succeeding picture of specified name

AGI_RCSP( pname, pstart, x, y, picid, status )
    Recall succeeding picture embracing a position

3.6 Labels (both libraries)

AGI_ILAB( picid, label, status )
    Inquire label of a picture

AGI_SLAB( picid, label, status )
    Store label in picture

3.7 Reference (both libraries)

AGI_GTREF( picid, mode, datref, status )
    Get a reference object from a picture

AGI_PTREF( datref, picid, status )
    Store a reference object in a picture

3.8 Transformations (both libraries)

AGI_TCOPY( trnloc, picid, status )
    Copy a transformation structure to the database

AGI_TDDTW( picid, nxy, dx, dy, wx, wy, status )
    Transform double precision data to world coordinates

AGI_TDTOW( picid, nxy, dx, dy, wx, wy, status )
    Transform data to world coordinates

AGI_TNEW( ncd, ncw, dtow, wtod, picid, status )
    Store a transformation in the database

AGI_TRUNC( status )
    Truncate the AGI database file by removing unused space

AGI_TWTDD( picid, nxy, wx, wy, dx, dy, status )
    Transform double precision world to data coordinates

AGI_TWTOD( picid, nxy, wx, wy, dx, dy, status )
    Transform world to data coordinates

3.9 Inquiries (both libraries)

AGI_IBASE( picid, status )
    Inquire base picture for current device

AGI_ICOM( coment, status )
    Inquire comment for the current picture

AGI_ICURP( picid, status )
    Inquire the current picture

AGI_INAME( pname, status )
    Inquire name of the current picture

AGI_IPOBS( picid, lobs, status )
    Is current picture obscured by another?

AGI_ISAMD( picid, lsame, status )
    Inquire if pictures are on same device

AGI_ISAMP( picid, lsame, status )
    Inquire if two pictures are the same

AGI_ITOBS( nxy, x, y, ltobs, status )
    Inquire if test points are obscured

AGI_IWOCO( wx1, wx2, wy1, wy2, status )
    Inquire world coordinates of current picture

3.10 More (both libraries)

AGI_IMORE( picid, lmore, status )
    Inquire if a MORE structure exists

AGI_MORE( picid, acmode, morloc, status )
    Return an HDS locator to a MORE structure

3.11 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 in Section 8.

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

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.

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.