AGI can be used independently of a graphics system. When AGI is opened, no specific graphics system is associated with the database. When it is required to display something on a device, a graphics package is selected and the plotting done. The opening and closing of the package is performed separately from the opening and closing of the database 1. The following simplified block diagram illustrates this operation.
The first step of opening the database is done by calling either AGI_ASSOC or AGI_OPEN. AGI_ASSOC is used in ADAM tasks and obtains the name of the device through the ADAM parameter system.
PARAM is the name of the parameter in the ADAM interface file through which the device name is to be obtained. It should be stressed that AGI_ASSOC does not open the specified device for plotting, it opens the database entry for that device. The opening of the device for plotting is handled by the routines specific to a particular graphics package, for instance the AGS_ routines. ACMODE is an access mode which has a particular meaning for AGI. It does not refer to the access mode of the database, i.e. whether an application can update the database or not, but instead it refers to the access mode of the graphics device. It is used to control whether the device should be cleared when it is opened by a graphics package. The possible modes are ‘READ’, ‘UPDATE’, and ‘WRITE’. The modes ‘READ’ and ‘UPDATE’ leave the display as it is; the ‘WRITE’ mode clears the area of the display specified by the current picture returned in PICID. PICID returns an identifier to the current picture in the database; on opening the database this will be the picture that was current when the database was last accessed. If there is no previous entry in the database for this device then a ‘BASE’ picture will be created. This ‘BASE’ picture will fill the display area and will be created with a default world coordinate system, in the same way as the SGS base zone.
AGI_OPEN is used in non-ADAM tasks.
WKNAME is the device name. The other arguments are the same as those in AGI_ASSOC.
The given device name, whether passed through the parameter system or the argument list, should obey the syntax rules described in the next Section (4.2).
Devices with windowing capabilities allow the user to change the size of the display window between applications. This has a detrimental affect on AGI because the size of the base picture, and the relationship between pictures changes. Rather than considering this an error status, which could terminate an application, AGI deletes all the pictures on this device, creates a new base picture and sends the following message to the user.
This allows any application that can continue from such a situation to do so. For instance it is sensible to allow a display application that uses the current picture for output to continue in this situation. In this case, after the existing database entries have been deleted, the current picture will be the base picture.
For applications linked with the GKS based AGI library the user should supply a valid GNS device name (SUN/57) which AGI converts into an internal name that locates the workstation structure in the database. For devices that have more than one plotting plane, it is desirable that AGI treat pictures plotted on the different planes as being on the same device, so that plots on the overlay plane can be lined up with plots below them. Database entries for pictures on these different planes, which are different devices in GKS and SGS, will therefore appear in the same AGI workstation structure.
The AGP library is based on native-PGPLOT style device names of the form <devname>/<devtype>.
The graphics device to be used is selected by the <devtype> component. The <devname> component
before the / will be some form of name used by the device driver (typically a physical device on the
system or an output file name) but is often omitted as most drivers contain a sensible default value.
For example a graphics device of just /gwm will open a Starlink GWM X11 window with a default
window name of xwindows while a complete specification of mywindow/gwm will open a GWM window
with the name mywindow.
For native-PGPLOT based applications to co-exist with GKS-based ones it is important that users can continue to supply “old_style” GKS device names where these have a sensible translation. Where there IS such a translation the AGI database records must also be made to match. Logic has been incorporated into the AGP library to perform this name translation process. Also in AGP typing a single ? for the device name will list all the possible translations. At the time of writing this document these were (but see also section Section 7):
As an example of the overall effect native-PGPLOT graphics specifications of xwindows/gwm, /gwm or
xwindows are all valid and equivalent in the AGP version of the AGI library. They will select a
GWM window with name xwindows which will have AGI database records identical to
those created by the AGI library routines for the graphics device with the GNS name of
xwindows.
The user will still see some slight differences from previous GKS behaviour when using GKS style device names via this scheme. For example:
Pictures are flagged by means of an integer identifier (the picture identifier) which combines knowledge of a device name and a picture number in the same way that an SGS zone number does. Both AGI_ASSOC and AGI_OPEN return a picture identifier to the current picture on the given device. Pictures in the database can only be referenced by means of these identifiers which are returned to the application from the appropriate AGI routines. These identifiers should only be passed on to other AGI routines and should not be altered in any way by an application.
Once a picture is no longer required it is good practice to release it using AGI_ANNUL which liberates internal workspace. Picture identifiers can be automatically released by using a begin-end block (see Section 4.5).
It may seem a bit premature to close the database having only just described how to open it, but some things are best explained at this stage. In an ADAM environment the routine AGI_CANCL cancels the association of the specified parameter and performs specific tidying up operations concerning that parameter. If the parameter association has to be retained outside the program then AGI_CANCL should not be called.
If the workstation structure is opened by AGI_OPEN, a call to AGI_CLOSE should be used to close it.
General tidying up operations (e.g. closing the database) are performed when the last active identifier has been annulled, either with AGI_ANNUL or AGI_END. It is important that tasks clean up all their identifiers otherwise unusual side effects may occur if the executable image is permanently resident in memory (such as an ADAM task).
Once the database has been closed, AGI_TRUNC can be called to truncate the database file to remove any unused space, thus keeping the file size at a minimum.
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.
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).
The database is stored in an HDS container file named agi_<node>.sdf in the directory defined by the environment variable AGI_USER or in your home directory if AGI_USER hasn’t been defined (HDS is the Hierarchical Data System described in SUN/92). The name of the node is included in the file name to prevent two or more devices which have the same name but are on different nodes causing a conflict. The contents of the file can be examined using the ADAM application TRACE. In certain circumstances the database file may become corrupted. If this is suspected it is best to delete the appropriate file and start again.
The name of the container file can be optionally changed by defining the environment variable AGI_NODE to be equivalent to some user defined string. If such a environment variable exists then the container file is constructed by replacing the default node with the new string. Thus if the environment variable AGI_NODE is defined to be ‘nonode’ then the container file will have the name agi_nonode.sdf in the directory AGI_USER. This mechanism can be used to pick up a database created on a different node by defining the logical name to be equivalent to the required node name.
1There are routines, such as AGP_ASSOC and AGP_DEASS, which package both operations in one unit.