As with all other packages in ADAM, the only access to objects outside of application programs is via ADAM program parameters. The connection between graphics devices and the application program is controlled by means of a few environment level routines.
SGS has four environment level subroutines (the SGS ‘parameter’ or SGSPAR routines) which provide the necessary interaction with the outside world. They are :
| Subroutine | Function |
| SGS_ASSOC | Associate a graphics workstation with a parameter and open it. |
| SGS_ANNUL | Close a graphics workstation without cancelling the parameter. |
| SGS_CANCL | Close a graphics workstation and cancel the parameter. |
| SGS_DEACT | De-activate ADAM SGS. |
Here is a skeletal example of a program using SGS :
SGS_ASSOC should be the first SGS routine to be called in the application. It obtains (via the parameter
system) the name of the graphics workstation to be used, creates an initial SGS zone on the
workstation, and returns an SGS zone identifier which can be used in subsequent SGS subroutine
calls.
The first argument of SGS_ASSOC is an ADAM program parameter. It should be defined to be a
graphics device parameter in the interface module for the application (see the example interface file in
section4). The value of this parameter should be the name of a workstation as defined by GNS (see
SUN/57).
The second argument is the access mode required. This can be one of :
’READ’ ’WRITE’ ’UPDATE’ Note that the facility to prevent screen clearing is specific to RAL GKS and is not implemented for all workstations.
The third argument is the SGS zone identifier returned to the application.
The fourth argument is the usual status value. It follows the ADAM error strategy as described in SUN/104.
When the application has finished using the workstation, it should be closed using SGS_CANCL unless it
is required to keep the parameter active (to update a global parameter for example), in which case
SGS_ANNUL should be used.
When the application has finished using SGS, it should be de-activated by calling SGS_DEACT.
PGPLOT has four environment level subroutines (the PGPLOT ‘parameter’ or PGPPAR routines) which provide the necessary interaction with the outside world. They are :
| Subroutine | Function |
| PGP_ASSOC | Associate a graphics workstation with a parameter and open it. |
| PGP_ANNUL | Close a graphics workstation without cancelling the parameter. |
| PGP_CANCL | Close a graphics workstation and cancel the parameter. |
| PGP_DEACT | De-activate ADAM PGPLOT. |
Here is a skeletal example of a program using PGPLOT :
Note the close similarity with the SGS skeleton program. PGP_ASSOC should be the first PGPLOT
routine called in the application. It obtains (via the parameter system) the name of the graphics
workstation to be used, opens the workstation, and returns a PGPLOT unit number. PGPLOT only
supports one graphics device open at one time so this unit number is always returned as
one1.
The first, second and last arguments of PGP_ASSOC are the same as the corresponding arguments of
SGS_ASSOC.
The third and fourth arguments are the number of sub-plots per page in X and Y (c.f. PGBEG).
The fifth argument is the unit identifier returned to the application.
When the application has finished using the workstation, it should be closed using PGP_CANCL unless it
is required to keep the parameter active (to update a global parameter for example), in which case
PGP_ANNUL should be used.
When the application has finished using PGPLOT, it should be de-activated by calling
PGP_DEACT.
GKS has five environment level subroutines (the GKS ‘parameter’ or GKSPAR routines). Four provide the necessary interaction with the outside world and one gives access to the GKS internal status. They are :
| Subroutine | Function |
| GKS_ASSOC | Associate a graphics workstation with a parameter and open it. |
| GKS_ANNUL | Close a graphics workstation without cancelling the parameter. |
| GKS_CANCL | Close a graphics workstation and cancel the parameter. |
| GKS_DEACT | De-activate ADAM GKS. |
| GKS_GSTAT | Inquire whether GKS has reported an error (see Section 5). |
Here is a skeletal example of a program using GKS :
Note the close similarity with the SGS skeleton program. GKS_ASSOC should be the first GKS routine to
be called in the application. It obtains (via the parameter system) the name of the graphics workstation
to be used, opens it, and returns a GKS workstation identifier which can be used in subsequent GKS
subroutine calls.
The notes in the previous section on the arguments of SGS_ASSOC apply equally well to GKS_ASSOC
with the exception that the third argument is a GKS workstation identifier rather than an SGS zone
identifier.
The workstation is closed using GKS_ANNUL or GKS_CANCL when the application has finished using
it.
When the application has finished using GKS, it should be de-activated by calling GKS_DEACT.
1PGBEG has a similar redundant argument so that if, one day, PGPLOT is extended to support multiple devices, existing
programs would not have to be changed.