If you are writing an ADAM application you should use the routines described in the ADAM Graphics Programmer’s Guide (SUN/113) to open and close workstations and not the routines described here.
Most programs that are to perform graphics I/O via SGS begin by calling SGS_OPEN and end by calling SGS_CLOSE:
The arguments of the OPEN call are as follows. WKSTN is the workstation name, a character string specifying the required graphics workstation. IZONID receives from SGS the ‘zone identifier’, a number allocated by SGS which we may need later to refer back to this workstation. ISTAT is the status, which will be zero if the OPEN has succeeded.
Friendly workstation names (e.g. ‘PLOTTER’) can be given to graphics workstations, either by the user
or by the system manager, and then specified in the SGS_OPEN call. More details can be found in
Appendix A; consult your system manager about local conventions. Alternatively, the two numbers
needed to specify the workstation—the workstation type (what sort of device) and the connection
identifier (which one)—can be given directly, as a character string consisting of 2 numbers separated
by a comma. A list of available workstation types can be obtained by running the program
/star/bin/examples/sgs_workstations1.
If the program just prints a message stating that the database could not be opened you should inform
your system manager.
Broadly speaking, the connection identifier specifies which of several workstations of the nominated type is to be opened. Exactly how connection IDs are mapped onto real devices depends on the GKS implementation being used. For example, in RAL GKS, for devices that are terminals, 5 will be the terminal which you have logged on to. For the metafile workstations the connection identifier is the Fortran unit to which the output will be sent for temporary storage on disk.
As an example, if we are working on a Tektronix 4010 terminal, the mandatory open call might be:
If, instead, we wish to create a metafile on disk we could use:
The purpose of the zone identifier will become clearer later on; suffice it to say at this stage that this number (which is allocated by SGS and cannot be set or otherwise processed by the user’s program) allows the program to refer back to the full display surface of the workstation that has been opened. A zone set up by SGS_OPEN or SGS_OPNWK is called a ‘base zone’.
Should any error messages be output by the SGS or GKS routines, they will be reported through the Starlink error reporting system (EMS - see SUN/104)
A formatted table of the workstation names known to SGS can be output by calling SGS_WLIST:
where LUN is the FORTRAN logical unit on which the table should be written. Each name is accompanied by a one-line description of the workstation.
If you want the table to appear on the user’s terminal, and you have not set up your own logical units, specify a unit number of 6, which is by default directed to the terminal. For example:
If you want to perform your own formatting of the list, or manipulate the names in some other way, this can be done with SGS_WNAME. See section 10 for more information. SGS_WLIST and SGS_WNAME are the only SGS routines that can be called before SGS has been opened.
The appearance of a name in the list does not guarantee that the workstation can be opened (it could, for example, be in use by someone else), nor does it mean that no other valid names exist. However, it does provide a mechanism for programs to help users with workstation names which is always up-to-date, even when programs are copied from one computer to another. If the graphics devices on a system change, it only requires the system manager to edit a table, and all SGS programs not only have access to new devices but can also reflect the changed situation in their help information.
Programs should not make assumptions about the properties of workstations given the workstation name or type, both of which are subject to change. If special features of a device are to be exploited, their existence must be established via the appropriate SGS and GKS inquiry calls.
It is a central philosophy of SGS that only one workstation should be active at once. However, multiple workstations may be open at once, and plotting may switch between them. Successive workstations may be opened with calls to the routine SGS_OPNWK:
WKSTN is the workstation name, IZONID receives the zone identifier for the base zone (see section 4) and ISTAT is as before.
On each occasion that SGS_OPNWK is called, previously active workstations are deactivated before plotting switches to the new workstation. Thus, if the program is to plot first on a VDU then later on a plotter, it is best to open the plotter in the SGS_OPEN call and then to use SGS_OPNWK to open the VDU. Plotting on the latter can then begin.
Multiple SGS_OPEN calls to the same workstation are permitted; on each occasion a new base zone is created.
Individual workstations can be closed by means of:
where IZONID must be a base zone; if there are other base zones on the workstation the specified zone is released but the workstation is not closed.
Switching between multiple workstations is accomplished by the ‘select zone’ routine which will be described in the next section.
If we want more flexible control—for example the ability to have several workstations active at once—this is available directly through the GKS activate/deactivate routines:
A final call to SGS_CLOSE will always leave the system correctly terminated.
It is sometimes necessary to distinguish between different parts of a graph. There are a variety of ways this might be achieved, depending on the characteristics of the particular graphics device concerned: for example by plotting in different colours, or by using dotted lines, or by varying the line width. Individual control over all of these options is possible within GKS; the SGS package offers instead a simplified facility where one of a small number of clearly distinguishable line qualities may be selected, each specified by an SGS ‘pen number’. The call is:
where NPEN is the number of the SGS pen—an integer greater than 0.
SGS pen number 1 is the default, and is the ‘normal’ pen for the device—a solid white line on a VDU, for example, or a black line of ordinary width on a plotter. SGS pens 1 to 5 may be assumed to be available and will correspond—depending on the device—to different colours or different styles of dashed line. Pen numbers greater than 5 may be available depending on the device. New pens may be defined or existing ones redefined with the GKS set polyline representation function (GSPLR) but should only be done immediately after opening the workstation to avoid causing implicit regeneration of the picture.
Appendix B should be consulted before using GKS facilities directly.
The last requested SGS pen number can be obtained by means of:
For efficiency, both SGS and GKS save up output in memory and send it to the graphics device in batches. Occasionally this may not be appropriate. For example an application program may plot a graph and then ask the user if the plot is satisfactory; it is clearly important that the whole plot has been completed before user input is solicited. In such cases the call:
causes any pending output to be sent immediately (to all active workstations). Unnecessary calls to SGS_FLUSH will have no significant ill effects (other than defeating any benefits from the buffering of output)2.
It is particularly important that SGS_FLUSH be called before any sequence of direct calls to GKS routines. For the same reason SGS_CLOSE must be called before your program exits, otherwise the plot may be incomplete or even absent.
In some sophisticated applications it may be useful or even necessary to separate the opening of SGS/GKS, and the opening of the first workstation, for example in order to make inquiries about the capabilities of a workstation before opening it. SGS/GKS can be opened with:
where ISTAT is as for SGS_OPEN. LUN is the logical unit passed to GOPKS but this is not used by the GKS implementation distributed by Starlink. GKS is then open and GKS functions may be called (at least one workstation must be opened and activated before any plotting can be done of course). Workstations can then be opened with calls to SGS_OPNWK in the normal way.
The GKS standard specifies that when a workstation is opened its display surface must be cleared. This is usually exactly what is required, but for some system architectures this is a problem as it prevents one program adding to, or interacting with, a picture drawn by another. An escape function has therefore been implemented in Starlink’s version of RAL GKS to suppress the screen clear when a workstation is opened. This function is only available on interactive workstations, not on hard copy devices, and futhermore this feature will not be available in other GKS implementations. It should therefore only be used when no other solution is possible.
will suppress the clearing of the display surface when the next workstation is opened provided that the workstation supports this feature. If it does not, no error message is output and the display surface is cleared as usual. After SGS_OPNWK has been called, the normal GKS behaviour will have been restored (because SGS_OPNWK explicitly resets the flag), and so SGS_CLRFG has to be called again each time a new workstation is opened. This is not true if GOPWK is used to open the workstation, in which case a return to normal behaviour requires:
1if you are using this software on a non-Starlink machines you mave to replace /star by some other path
name.
2Except when plotting dashed or dotted lines as SGS_FLUSH will cause the dash pattern to be restarted; if the line is being plotted with points very close together and SGS_FLUSH is called after each point the line may appear to be solid.