A GKS Subroutine Library for RT-11 (V0.20) James V. Flatten Ames Laboratory, ISU/DOE NOTE This GKS subroutine library was written by Jim Flatten of the Ames Laboratory at Iowa State University as part of U.S. Department of Energy contract W-7405-ENG-82. The right to use this software release is allowed in the public domain. The author, Ames Laboratory, and USDOE assume no responsibility as to the correctness of the code nor the appropriateness for such use as it may be applied. Any comments may be addressed to Jim Flatten; 258I Metals Development; Ames Laboratory; Ames, IA 50011 13 May 87 20:28:36 CHAPTER 1 GKS FOR RT-11 (V0.20) 1-1 1.1 INTRODUCTION 1-1 1.2 CONCEPTS 1-2 1.3 OUTPUT PRIMITIVES 1-3 1.4 OUTPUT PRIMITIVE ATTRIBUTES 1-4 1.5 WORKSTATIONS 1-5 1.6 COORDINATE SYSTEMS AND TRANSFORMATIONS 1-6 1.6.1 Normalization transformations 1-6 1.6.2 Clipping 1-7 1.6.3 Workstation transformations 1-7 CHAPTER 2 FUNCTIONAL DESCRIPTIONS 2-1 2.1 ACTIVATE WORKSTATION 2-2 2.2 CLOSE GKS 2-3 2.3 CLEAR WORKSTATION 2-4 2.4 CLOSE WORKSTATION 2-6 2.5 DEACTIVATE WORKSTATION 2-7 2.6 OPEN GKS 2-8 2.7 OPEN WORKSTATION 2-9 2.8 POLYMARKER 2-10 2.9 INQUIRE COLOR FACILITIES 2-11 2.10 INQUIRE CURRENT CHARACTER HEIGHT 2-12 2.11 INQUIRE CHARACTER UP VECTOR 2-13 2.12 INQUIRE CLIPPING INDICATOR 2-14 2.13 INQUIRE CURRENT NORMALIZATION TRANSFORMATION NUMBER 2-15 2.14 INQUIRE COLOR REPRESENTATION 2-16 2.15 INQUIRE FILL AREA COLOR INDEX 2-18 2.16 INQUIRE FILL AREA INTERIOR STYLE 2-19 2.17 INQUIRE LINETYPE 2-20 2.18 INQUIRE LEVEL OF GKS 2-21 2.19 INQUIRE POLYMARKER INDEX 2-22 2.20 INQUIRE NORMALIZATION TRANSFORMATION 2-23 2.21 INQUIRE POLYLINE COLOR INDEX 2-24 2.22 INQUIRE POLYMARKER COLOR INDEX 2-25 2.23 INQUIRE TEXT ALIGNMENT 2-26 2.24 INQUIRE WORKSTATION CONNECTION AND TYPE 2-27 2.25 INQUIRE WORKSTATION TRANSFORMATION 2-28 2.26 SET CHARACTER HEIGHT 2-30 2.27 SET CHARACTER UP VECTOR 2-31 2.28 SET CLIPPING INDICATOR 2-32 2.29 SELECT NORMALIZATION TRANSFORMATION 2-33 2.30 SET FILL AREA COLOR INDEX 2-34 2.31 SET FILL AREA INTERIOR STYLE 2-35 2.32 SET LINE TYPE 2-36 2.33 SET MARKERTYPE 2-37 2.34 SET POLYLINE COLOR INDEX 2-38 2.35 SET TEXT ALIGNMENT 2-39 2.36 SET TEXT COLOR INDEX 2-40 2.37 SET VIEWPORT 2-41 2.38 SET WORKSTATION VIEWPORT 2-42 2.39 SET WORKSTATION WINDOW 2-43 2.40 SET WINDOW 2-44 2.41 TEXT 2-45 2.42 UPDATE WORKSTATION 2-47 CHAPTER 3 USING GKS WITH RT-11 3-1 3.1 INCORPORATING GKS INTO FORTRAN SOURCE PROGRAMS 3-1 -i- 3.2 LINKING PROGRAMS WITH GKS 3-2 3.2.1 Linking One Driver 3-2 3.2.2 Linking More than One Driver 3-2 3.3 RUNNING PROGRAMS THAT USE GKS 3-3 -ii- CHAPTER 1 GKS FOR RT-11 (V0.20) 1.1 INTRODUCTION This document describes an implementation of the Graphical Kernal System (GKS) for the RT-11 operating system running on a PDP-11 computer. GKS is both an international standard (ISO 7942-1985) and an American National Standard (ANSI X3.124-1985). The standard specifies twelve different levels. This implementa- tion is the lowest level of GKS, GKS level MA. As such it has no support for graphical input, segment support or metafile input or output. Level MA was chosen to keep the graphical subroutine library small and efficient for applications running under RT-11. Three device drivers are provided. The drivers are for the HP7475 6 pen plotter (DRV745.OBJ), the Tektronix 4107 color ter- minal (DRV407.OBJ) and the Visual 550 terminal (DRVV50.OBJ, Tek 4010 compatible). More than one driver may be loaded at a time. Source code for the device drivers is included so that users can use them as templates to generate new device drivers. The driver interface is loosely based on the emerging Computer Graphics In- terface (CGI) being developed by the X3H3.3 committee. This release of GKS (V0.20) for RT-11 is incomplete. Ver- sion 1.00 will be complete and will be available by the Fall 1987 DECUS Symposium in Anaheim. In particular, the Fill Area output primitive has not been implemented, error handling is spotty (some errors cause something to happen, others don't), the do- cumentation is incomplete and a few inquiry subroutines produce no result (specifically GQCR, INQUIRE COLOR REPRESENTATION and GQCF, INQUIRE COLOR FACILITIES), they are just stubs. There are also sure to be bugs. In spite of these problems, you can still do useful work with the package as it stands. The implemented output primitives are POLYLINE, POLYMARKER, and TEXT. All the specified attributes for these primitives are implemented. My intention has been to follow the GKS standard exactly. Where differences occur, it is because the package is incomplete at this time, coding or design errors have crept in or because of my misinterpretation of the intent of the standard. Please -1-1- GKS FOR RT-11 (V0.20) Introduction advise me of discrepancies and be aware that there may be signi- ficant changes between now and the next release, if and when such discrepancies are found and corrected. Much of the following documentation has been taken directly from the ANSI GKS document. Material about segments and graphi- cal input has been removed in most places however, to avoid references to functionallity that is not, and probably will not be, a part of this subroutine library. 1.2 CONCEPTS Graphical output generated by GKS is built up from two groups of basic elements called output primitives and primitive attributes. Output primitives are abstractions of basic actions a device can perform, such as drawing lines, and printing character strings. Attributes control the appearance of output primitives on a device, such as linestyle, color, and character height. Non-geometric aspects, such as color, can be controlled for each workstation individually, to make best use of its capa- bilities. Output and Input are the components of an abstract workstat- ion. A GKS workstation has zero or one display surfaces and zero or more input devices, such as keyboard, tablet and lightpen. The workstation presents these devices to the application program as a configuration of abstract devices thereby shielding the pro- grammer from the hardware peculiarities of a particular device. The geometrical information (coordinates) contained in out- put primitives can be subjected to transformations. These transformations perform mappings between three coordinate sys- tems, namely: 1. World Coordinates (WC), used by the application programmer; 2. Normalized Device Coordinates (NDC), used to define a uniform coordinate system for all workstations; 3. Device Coordinates (DC), one coordinate system per workstation, representing its display space coordinates. Output primitives and attributes are mapped from WC to NDC by normalization tranformations, and from NDC to DC by worksta- tion transformations. The attributes which control the appearance of parts of the picture on the display surface are organized in a uniform manner. Two groups of attributes apply to the appearance of each output primitive: primitive attributes and workstation attributes. Primitive attributes are specified modally and are forever -1-2- GKS FOR RT-11 (V0.20) Concepts associated with a primitive when it is created. The primitive attributes include all geometrical aspects of primitives, such as character height for text, and pattern size for fill area. In addition, the non-geometrical aspects of primitives are con- trolled by the primitive attributes in one of two ways. Either a single attribute is used to specify all the non-geometric aspects of the primitive by an index which points to a workstation depen- dent representation (set of values) or one attribute is used to specify each of the non-geometric aspects of the primitive in a workstation independent way. The former is referred to as bundled specification and the latter is referred to as individual specification. Level MA of GKS supports only individual specifications. At run time GKS can be in one of five different operating states. Associated with each state are the set of GKS functions allowed in this state, and a set of state variables. The operat- ing state concept and the state variables allow for proper speci- fication of initializations (for example, at OPEN WORKSTATION) and the effect of various functions, especially with respect to the maintenance of device independence. One special set of func- tions called inquiry functions is allowed in all states. They give read-only access to the state lists. In this way useful in- formation can be provided when errors occur. Other inquiry func- tions allow read-only access to the workstation descriptions, to allow the application program to adapt to particular workstation capabilities. Inquiry functions never cause errors. Instead they return information specifiying whether a valid inquiry was made. 1.3 OUTPUT PRIMITIVES The graphical information that is generated by GKS and routed to all active workstations is built up of basic pieces called output primitives. GKS level MA provides four output primitives: 1. POLYLINE 2. POLYMARKER 3. TEXT 4. FILL AREA The POLYLINE primitive draws a line from one point to another in ordered sets of X and Y values. The type of line (solid, dashed, dotted, etc) can be changed as can the color of the line. -1-3- GKS FOR RT-11 (V0.20) Output Primitives The POLYMARKER primitive draws a marker at each point of an ordered set of X and Y values. The type of marker ('+', '.', 'o', etc) can be changed as can the color of the marker. The TEXT primtive draws a character string, starting at a point specified in world coordinates. The height, color and justification of the text is controllable. The FILL AREA primitive draws a line from one point to another in ordered sets of X and Y values, including a line from X(N), Y(N) to X(1), Y(1). The resulting enclosed area is filled according to the current specification for fill area color and style. 1.4 OUTPUT PRIMITIVE ATTRIBUTES Each output primitive potentially has three types of attri- bute (geometric, non-geometric and identification). The first two type determine the exact appearance of the output primitive while the third attribute type is used in conjunction with input. The values of these attributes are set modally and are recorded in the GKS state list. A separate GKS function is provided for each primitive attribute to allow the application program to specify the value of an attribute without unnecessarily specify- ing the values of other attributes. During creation of an output primitive (that is, when one of the GKS output primitive func- tions is invoked) these values are associated with the primitive and cannot be changed afterwards. Geometric attributes control the geometric aspects of a primitive; these are aspects which affect the shape or size of a primitive (for example, CHARACTER HEIGHT for TEXT). Attributes of this type are workstation independent and, where appropriate, are expressed in world coordinates (for example, CHARACTER HEIGHT is expressed in world coordinates but TEXT PATH takes one of a set of enumerated values). They are defined separately for each primitive and a primitive may have zero, one or many geometric attributes. Current values of (workstation independent) geometric attri- butes, which are expressed in world coordinates, are stored in world coordinates. When they are associated with a primitive, the values are subject to the same transformations as the geometric data contained in the definition of the primitive. Hence, current values are unaffected by changes in the normaliza- tion transformation and the workstation transformation. Non-geometric attributes do not affect the shape or size of a primitive but merely affect its appearance (for example, line- type for POLYLINE, or color index for all primitives except CELL ARRAY). -1-4- GKS FOR RT-11 (V0.20) Output Primitive Attributes There is a separate attribute for each non-geometric aspect. As with the attributes controlling the geometric aspects, these attributes are workstation independent. 1.5 WORKSTATIONS GKS is based on the concept of abstract graphical worksta- tions. Workstations provide the logical interface through which the application program controls physical devices. For every type of workstation present in a GKS implementation (except for the special workstations), there exists a workstation description table which describes the capabilities and characteristics of the workstation. The application can inquire which capabilities are available and adapt its behavior accordingly. Each workstation has a type. GKS defines six workstation categories. They are: 1. Output 2. Input 3. Output and Input 4. Workstation Independent Segment Storage 5. GKS Metafile output 6. GKS Metafile input A workstation of category OUTPUT has only output capabilities and is the only workstation type supported by GKS Level MA. The application program references a workstation by means of a workstation identifier. Connection to a particular workstation is established by the function OPEN WORKSTATION, which associates the workstation identifier with a workstation type and a connec- tion identifier. The current state of each open workstation is kept in a workstation state list. Output primitives are sent to all active workstations and no others; an open workstation is made active by the function ACTIVATE WORKSTATION. An active workstation is made inactive by the function DEACTIVATE WORKSTATION; an open workstation is closed by the function CLOSE WORKSTATION. The following sequence of functions illustrates workstation selection: OPEN WORKSTATION (1) OPEN WORKSTATION (2) ACTIVATE WORKSTATION (1) -1-5- GKS FOR RT-11 (V0.20) Workstations Output functions {generated only on 1} ACTIVATE WORKSTATION (2) Output functions {generated on 1,2} DEACTIVATE WORKSTATION (1) Output functions {generated only on 2} CLOSE WORKSTATION (1) DEACTIVATE WORKSTATION (2) CLOSE WORKSTATION (2) 1.6 COORDINATE SYSTEMS AND TRANSFORMATIONS 1.6.1 Normalization transformations In GKS, the application programmer can compose his graphical picture from separate parts each of which, conceptually, is de- fined with its own world coordinate system (WC). The relative positioning of the separate parts is defined by having a single normalized device coordinate space (NDC) onto which all the de- fined world coordinate systems are mapped. A set of normaliza- tion transformations defines the mappings from the world coordinate systems onto the single normalized device coordinate space, which can be regarded as a workstation independent abstract viewing surface. For output, a single normalization transformation is current at any one time and this is used to transform world coordinates specified, for example in output primitives and geometric attri- butes, into normalized device coordinates. A normalization transformation is specified by defining the limits of an area in the world coordinate system (window) which is to be mapped onto a specified area of the normalized device coordinate space (viewport). Window and viewport limits specify rectangles parallel to the coordinate axes in WC and NDC. The rectangles include their boundaries. The normalization transfor- mation performs a mapping from WC onto NDC that includes transla- tion and differential scaling with positive scale factors for the two axes. Although NDC space conceptually extends to infinity, the part of NDC space in which the viewport needs to be located and that can be viewed at a workstation is the closed range [0,1]x[0,1]. -1-6- GKS FOR RT-11 (V0.20) COORDINATE SYSTEMS AND TRANSFORMATIONS Each normalization transformation is identified by a transformation number which is an integer between 0 and an im- plementation dependent value n which can be inquired from the GKS state list. The normalization transformation with transformation number 0 is the unity transformation which maps [0,1]x[0,1] in world coordinates to [0,1]x[0,1] in normalized device coordi- nates. It cannot be changed. Initially, all other normalization tranformations are set to a default transformation which is the same as transformation number 0. Different transformations can be specified at any time when GKS is open. Since GKS provides a number of different nor- malization transformations, it is possible for the application program to specify them prior to outputting the graphical pic- ture. The separate parts of the picture are output by selecting a particular normalization transformation before outputting the associated graphical primitives. However, specifying a normali- zation transformation, while the graphical output is taking place, is allowed. A normalization transformation may be selected by SELECT NORMALIZATION TRANSFORMATION, and it will be used for all output until another is selected. By default, normalization transforma- tion 0 is selected. 1.6.2 Clipping The viewport of a particular normalization transformation is used to define a clipping rectangle, as well as, with the window, specifying the normalization transformation. When the viewport of the current normalization transformation is set or when a nor- malization transformation is selected, the 'clipping rectangle' entry in the GKS state list is set to the resulting viewport of the current normalization transformation. Clipping to this clip- ping rectangle can either be enabled or disabled. There is a single global switch (the clipping indicator) which defines whether or not the clipping rectangle is to be used for clipping. 1.6.3 Workstation transformations Each open workstation can select independently some part of the NDC space in the range [0,1]x[0,1] to be displayed somewhere on the workstation display surface. A particular workstation transformation is a mapping from NDC space onto the device coor- dinates (DC) for that workstation. The units of device coordinates are meters on a device capa- ble of producing a precisely scaled image (for example most plotters) and appropriate workstation dependent units otherwise (for example, on a display unit with unknown monitor size). In -1-7- GKS FOR RT-11 (V0.20) COORDINATE SYSTEMS AND TRANSFORMATIONS either case the device coordinate system maps onto the display surface in the following way: 1. the DC origin is at the bottom left corner of the dis- play space; 2. the device coordinate units are related to the display space in such a way that a square in device coordinates appears as a square on the display surface (this is trivially true if the device coordinate units are meters); 3. x and y increase to the right and upwards respectively. On some devices, device coordinate units do not coincide with ad- dressable units, for example if the addressable units do not sa- tisfy the above conditions. The size of the display space in device coordinate units is recorded in the workstation description table. -1-8- CHAPTER 2 FUNCTIONAL DESCRIPTIONS -2-1- FUNCTIONAL DESCRIPTIONS ACTIVATE WORKSTATION 2.1 ACTIVATE WORKSTATION 2.1.1 FORTRAN calling sequence CALL GACWK (WKID) Input parameters: INTEGER WKID workstation identifier -2-2- FUNCTIONAL DESCRIPTIONS CLOSE GKS 2.2 CLOSE GKS 2.2.1 FORTRAN calling sequence CALL GCLKS 2.2.2 Description GKS is set into the operating state GKCL = 'GKS closed'. The GKS description table, GKS state list and the workstation description tables become unavailable. All GKS buffers are released and all GKS files are closed. NOTE GKS can be reopened by invoking the function OPEN GKS. 2.2.3 Errors 2 GKS not in proper state: GKS shall be in the state GKOP. -2-3- FUNCTIONAL DESCRIPTIONS CLEAR WORKSTATION 2.3 CLEAR WORKSTATION 2.3.1 FORTRAN calling sequence CALL GCLRWK (WKID, COFL) Input parameters: INTEGER WKID workstation identifier INTEGER COFL control flag (GCONDI, GALWAY) 2.3.2 Description All of the following actions are executed in the given sequence: 1. All deferred actions for the specified workstation are executed (without intermediate clearing of the display surface). 2. The surface is set to a clear state according to the control flag as follows: CONDITIONALLY: the display surface is cleared only if the 'display surface empty' entry in the workstation state list is NOTEMPTY. ALWAYS: the display surface is cleared 3. If the 'workstation transformation update state' entry in the workstation state list is PENDING, the 'current workstation window' and 'current workstation viewport' entries in the workstation state list are assigned the values of the 'requested workstation window' and 'requested workstation viewport' entries; the 'workstation transformation update state' entry is set to NOTPENDING. 4. The 'new frame action necessary at update' entry in the workstation state list is set to NO. 5. The 'display surface empty' entry in the workstation state list is set to EMPTY. -2-4- FUNCTIONAL DESCRIPTIONS CLEAR WORKSTATION 2.3.3 Errors 6 GKS not in proper state: GKS shall be either in the state WSOP or in the state WSAC 20 Specified workstation identifier is invalid 25 Specified workstation is not open 33 Specified workstation is of category MI 35 Specified workstation is of category INPUT -2-5- FUNCTIONAL DESCRIPTIONS CLOSE WORKSTATION 2.4 CLOSE WORKSTATION 2.4.1 FORTRAN calling sequence CALL GCLWK (WKID) Input parameters: INTEGER WKID workstation identifier 2.4.2 Description An implicit UPDATE WORKSTATION is performed for the specified workstation. The workstation state list is deallocated. The workstation identifier is deleted from the set of open worksta- tions in the GKS state list. The connection to the workstation is released. GKS is set into operating state GKOP if no workstations remain open. The display surface need not be cleared when CLOSE WORKSTATION is in- voked, but it may be cleared. 2.4.3 Errors 7 GKS not in proper state: GKS shall be in one of the states WSOP, WSAC, or SGOP. 20 Specified workstation identifier is invalid 25 Specified workstation is not open 29 Specified workstation is active 147 Input queue has overflowed -2-6- FUNCTIONAL DESCRIPTIONS DEACTIVATE WORKSTATION 2.5 DEACTIVATE WORKSTATION 2.5.1 FORTRAN calling sequence CALL GDAWK (WKID) Input parameters: INTEGER WKID workstation identifier 2.5.2 Description The specified workstation is marked inactive in the workstation state list. The workstation identifier is deleted from the set of active workstations in the GKS state list. GKS is set into the operating state WSOP = "At least one workstation open" if no workstation remains active. NOTE While a workstation is inactive, primitives are not sent to it. 2.5.3 Errors 3 GKS not in proper state; GKS shall be in the state WSAC. 20 Specified workstation identifier is invalid 30 Specified workstation is not active 33 Specified workstation is of category MI 35 Specified workstation is of category INPUT. -2-7- FUNCTIONAL DESCRIPTIONS OPEN GKS 2.6 OPEN GKS 2.6.1 FORTRAN calling sequence CALL GOPKS (ERRFIL, MEMSIZ) Input parameters: INTEGER ERRFIL error file connection ID INTEGER MEMSIZ dynamic memory to allocate 2.6.2 Description GKS is set into the operating state GKOP = "GKS open". The GKS state list is allocated and initialized. The GKS description table and the workstation description tables are made available. The entry 'error file' in the GKS error state list is set to the value specified by the first parameter. The permitted buffer area which can be used by GKS for internal purposes is limited (this implementation does not use this parameter). 2.6.3 Errors 1 GKS not in proper state: GKS shall be in the state GKCL 200 Specified error file is invalid -2-8- FUNCTIONAL DESCRIPTIONS OPEN WORKSTATION 2.7 OPEN WORKSTATION 2.7.1 FORTRAN calling sequence CALL GOPWK (WKID, CONID, WTYPE) Input parameters: INTEGER WKID workstation identifier INTEGER CONID connection identifier INTEGER WTYPE workstation type 2.7.2 Description If GKS is in operating state GKOP, it is set into the state WSOP = 'at least one workstation open'. GKS requests the operating system to establish the specified connection for a workstation characterized in the workstation description table by the 'workstation type'. The workstation state list is allocated and initialized. The workstation identifier is added to the set of open workstations in the GKS state list. OPEN WORKSTATION en- sures that the display surface is clear, but does not clear the surface needlessly. An attempt to open a workstation with the same connection identifier and workstation type as one already open causes error 26 to occur. 2.7.3 Errors 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP 20 Specified workstation identifier is invalid 21 Specified connection identifier is invalid 22 Specified workstation type is invalid 23 Specified workstation type does not exist 24 Specified workstation is open 26 Specified workstation cannot be opened 28 Workstation Independent Segment Storage is already open 42 Maximum number of simultaneously open workstations would be exceeded -2-9- FUNCTIONAL DESCRIPTIONS POLYMARKER 2.8 POLYMARKER 2.8.1 FORTRAN calling sequence CALL GPM (N, PX, PY) Input parameters: INTEGER N number of points REAL PX(N), PY(N) coordinates of points in world coordinates -2-10- FUNCTIONAL DESCRIPTIONS INQUIRE COLOR FACILITIES 2.9 INQUIRE COLOR FACILITIES 2.9.1 FORTRAN calling sequence CALL GQCF (WTYPE, ERRIND, NCOLI, COLA, NPCI) Input parameters: INTEGER WTYPE workstation type Output parameters: INTEGER ERRIND error indicator INTEGER NCOLI number of colors INTEGER COLA color available (GMONOC, GCOLOR) INTEGER NPCI number of predefined color indices 2.9.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the number of available colors or intensities is returned as 0, the workstation supports a continuous range of colors or intensities. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 22 Specified workstation type is invalid. 23 Specified workstation type does not exist. 39 Specified workstation is neither of category OUTPUT nor of category OUTIN 2.9.3 Errors none -2-11- FUNCTIONAL DESCRIPTIONS INQUIRE CURRENT CHARACTER HEIGHT 2.10 INQUIRE CURRENT CHARACTER HEIGHT 2.10.1 FORTRAN calling sequence CALL GQCHH (ERRIND, CHH) Output parameters: INTEGER ERRIND error indicator REAL CHH character height 2.10.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 2.10.3 Errors none -2-12- FUNCTIONAL DESCRIPTIONS INQUIRE CHARACTER UP VECTOR 2.11 INQUIRE CHARACTER UP VECTOR 2.11.1 FORTRAN calling sequence CALL GQCHUP (ERRIND, CHUX, CHUY) Input parameters: INTEGER ERRIND error indicator REAL CHUX, CHUY character up vector (WC) 2.11.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 2.11.3 Errors none -2-13- FUNCTIONAL DESCRIPTIONS INQUIRE CLIPPING INDICATOR 2.12 INQUIRE CLIPPING INDICATOR 2.12.1 FORTRAN calling sequence CALL GQCLIP (ERRIND, CLSW, CLRECT) Output parameters: INTEGER ERRIND error indicator INTEGER CLSW clipping indicator (GNCLIP, GCLIP) REAL CLRECT(4) clipping rectangle 2.12.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 2.12.3 Errors none -2-14- FUNCTIONAL DESCRIPTIONS INQUIRE CURRENT NORMALIZATION TRANFORMATION NUMBER 2.13 INQUIRE CURRENT NORMALIZATION TRANSFORMATION NUMBER 2.13.1 FORTRAN calling sequence CALL GQCNTN (ERRIND, CTNR) Output parameters: INTEGER ERRIND error indicator INTEGER CTNR current transformation number 2.13.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 2.13.3 Errors none -2-15- FUNCTIONAL DESCRIPTIONS INQUIRE COLOR REPRESENTATION 2.14 INQUIRE COLOR REPRESENTATION 2.14.1 FORTRAN calling sequence CALL GQCR (WKID, COLI, TYPE, ERRIND, CR, CG, CB) Input parameters: INTEGER WKID workstation identifier INTEGER COLI color index INTEGER TYPE type of returned values (GSET, GREALI) Output parameters: INTEGER ERRIND error indicator REAL CR, CG, CB color (red/green/blue intensities 2.14.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 7 GKS not in proper state: GKS shall be in one of the states WSOP, WSAC or SGOP. 20 Specified workstation identifier is invalid. 25 Specified workstation is not open. 33 Specified workstation is of category MI. 35 Specified workstation is of category INPUT. 36 Specified workstation is Workstation Independent Segment Storage. 86 Color index is invalid. 87 A representation for the specified color index has not been defined on this workstation. -2-16- FUNCTIONAL DESCRIPTIONS INQUIRE COLOR REPRESENTATION 2.14.3 Errors none -2-17- FUNCTIONAL DESCRIPTIONS INQUIRE FILL AREA COLOR INDEX 2.15 INQUIRE FILL AREA COLOR INDEX 2.15.1 FORTRAN calling sequence CALL GQFACI (ERRIND, COLI) Input parameters: INTEGER ERRIND error indicator INTEGER COLI fill area color index 2.15.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 2.15.3 Errors none -2-18- FUNCTIONAL DESCRIPTIONS INQUIRE FILL AREA INTERIOR STYLE 2.16 INQUIRE FILL AREA INTERIOR STYLE 2.16.1 FORTRAN calling sequence CALL GQFAIS (ERRIND, INTS) Output parameters: INTEGER ERRIND error indicator INTEGER INTS fill area interior style (GHOLLO, GSOLID, GPATTR, GHATCH) 2.16.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 2.16.3 Errors none -2-19- FUNCTIONAL DESCRIPTIONS INQUIRE LINETYPE 2.17 INQUIRE LINETYPE 2.17.1 FORTRAN calling sequence CALL GQLN (ERRIND, LTYPE) Input parameters: INTEGER ERRIND error indicator INTEGER LTYPE linetype 2.17.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 2.17.3 Errors none -2-20- FUNCTIONAL DESCRIPTIONS INQUIRE LEVEL OF GKS 2.18 INQUIRE LEVEL OF GKS 2.18.1 FORTRAN calling sequence CALL GQLVKS (ERRIND, LEVEL) Output parameters: INTEGER ERRIND error indicator INTEGER LEVEL level of GKS (LMA, LMB, LMC, L0A, L0B, L0C, L1A, L1B, L1C, L2A, L2B, L2C) -2-21- FUNCTIONAL DESCRIPTIONS INQUIRE POLYMARKER INDEX 2.19 INQUIRE POLYMARKER INDEX 2.19.1 FORTRAN calling sequence CALL GQMK (ERRIND, MTYPE) Output parameters: INTEGER ERRIND error indicator INTEGER MTYPE marker type 2.19.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 2.19.3 Errors none -2-22- FUNCTIONAL DESCRIPTIONS INQUIRE NORMALIZATION TRANSFORMATION 2.20 INQUIRE NORMALIZATION TRANSFORMATION 2.20.1 FORTRAN calling sequence CALL GQNT (NTNR, ERRIND, WINDOW, VIEWPT) Input parameters: INTEGER NTNR normalization transformation number Output parameters: INTEGER ERRIND error indicator REAL WINDOW(4) window limits in world coordinates WXMIN, WXMAX, WYMIN, WYMAX REAL VIEWPT(4) viewport limits in normalized device coordinates VXMIN, VXMAX, VYMIN, VYMAX 2.20.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 50 Transformation number is invalid 2.20.3 Errors none -2-23- FUNCTIONAL DESCRIPTIONS INQUIRE POLYLINE COLOR INDEX 2.21 INQUIRE POLYLINE COLOR INDEX 2.21.1 FORTRAN calling sequence CALL GQPLCI (ERRIND, COLI) Output parameters: INTEGER ERRIND error indicator INTEGER COLI polyline color index 2.21.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 2.21.3 Errors none -2-24- FUNCTIONAL DESCRIPTIONS INQUIRE POLYMARKER COLOR INDEX 2.22 INQUIRE POLYMARKER COLOR INDEX 2.22.1 FORTRAN calling sequence CALL GQPMCI (ERRIND, COLI) Output parameters: INTEGER ERRIND error indicator INTEGER COLI polymarker color index 2.22.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 2.22.3 Errors none -2-25- FUNCTIONAL DESCRIPTIONS INQUIRE TEXT ALIGNMENT 2.23 INQUIRE TEXT ALIGNMENT 2.23.1 FORTRAN calling sequence CALL GQTXAL (ERRIND, TXALH, TXALV) Output parameters: INTEGER ERRIND error indicator INTEGER TXALH text alignment horizontal (GAHNOR, GALEFT, GACENT, GARITE) INTEGER TXALV text alignment vertical (GAVNOR, GATOP, GACAP, GAHALF, GABASE, GABOTT) 2.23.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 2.23.3 Errors none -2-26- FUNCTIONAL DESCRIPTIONS INQUIRE WORKSTATION CONNECTION AND TYPE 2.24 INQUIRE WORKSTATION CONNECTION AND TYPE 2.24.1 FORTRAN calling sequence CALL GQWKC (WKID, ERRIND, CONID, WTYPE) Input parameters: INTEGER WKID workstation identifier Output parameters: INTEGER ERRIND error indicator INTEGER CONID connection identifier INTEGER WTYPE workstation type 2.24.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 7 GKS not in proper state: GKS shall be in one of the states WSOP, WSAC or SGOP. 20 Specified workstation identifier is invalid 25 Specified workstation is not open 2.24.3 Errors none -2-27- FUNCTIONAL DESCRIPTIONS INQUIRE WORKSTATION TRANSFORMATION 2.25 INQUIRE WORKSTATION TRANSFORMATION 2.25.1 FORTRAN calling sequence CALL GQWKT (WKID, ERRIND, TUS, RWINDO, CWINDO, RVIEWP, CVIEWP) Input parameters: INTEGER WKID workstation identifier Output parameters: INTEGER ERRIND error indicator INTEGER TUS workstation transformation update state (GNPEND, GPEND) REAL RWINDO(4) requested workstation window in NDC RWXMIN, RWXMAX, RWYMIN, RWYMAX REAL CWINDO(4) current workstation window in NDC CWXMIN, CWXMAX, CWYMIN, CWYMAX REAL RVIEWP(4) requested workstation viewport in DC RVXMIN, RVXMAX, RVYMIN, RVYMAX REAL CVIEWP(4) current workstation viewport in DC CVXMIN, CVXMAX, CVYMIN, CVYMAX 2.25.2 Description If the inquired information is available, the error indicator is returned as 0 and the values are returned in the output parame- ters. The workstation transformation update state is PENDING if a workstation transformation change has been requested but not yet provided. If the inquired information is not available, the values re- turned in the output parameters are set to one of the following error numbers to indicate the reason for non-availability: 7 GKS not in proper state: GKS shall be in one of the states WSOP, WSAC or SGOP. 20 Specified workstation identifier is invalid 25 Specified workstation is not open 33 Specified workstation is of category MI 36 Specified workstation is Workstation Independent Segment Storage 50 Transformation number is invalid -2-28- FUNCTIONAL DESCRIPTIONS INQUIRE WORKSTATION TRANSFORMATION 2.25.3 Errors none -2-29- FUNCTIONAL DESCRIPTIONS SET CHARACTER HEIGHT 2.26 SET CHARACTER HEIGHT 2.26.1 FORTRAN calling sequence CALL GSCHH (CHH) Input parameters: INTEGER CHH character height -2-30- FUNCTIONAL DESCRIPTIONS SET CHARACTER UP VECTOR 2.27 SET CHARACTER UP VECTOR 2.27.1 FORTRAN calling sequence CALL GSCHUP (CHUX, CHUY) Input parameters: REAL CHUX, CHUY character up vector (WC) -2-31- FUNCTIONAL DESCRIPTIONS SET CLIPPING INDICATOR 2.28 SET CLIPPING INDICATOR 2.28.1 FORTRAN calling sequence CALL GSCLIP (CLSW) Input parameters: INTEGER CLSW clipping indicator (GNCLIP, GCLIP) -2-32- FUNCTIONAL DESCRIPTIONS SELECT NORMALIZATION TRANSFORMATION 2.29 SELECT NORMALIZATION TRANSFORMATION 2.29.1 FORTRAN calling sequence CALL GSELNT (TNR) Input parameters: INTEGER TNR transformation number -2-33- FUNCTIONAL DESCRIPTIONS SET FILL AREA COLOR INDEX 2.30 SET FILL AREA COLOR INDEX 2.30.1 FORTRAN calling sequence CALL GSFACI (COLI) Input parameters: INTEGER COLI fill area color index 2.30.2 Description The 'current fill area color index' entry in the GKS state list is set to the value specified by the parameter. This value is used for the display of subsequent FILL AREA output primitives. The color index is a pointer into the color tables of the workstations. If the specified color index is not present in a workstation color table, a workstation dependent color index is used on that workstation. 2.30.3 Errors 8 GKS not in proper state; GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 85 Color index is less than zero. -2-34- FUNCTIONAL DESCRIPTIONS SET FILL AREA INTERIOR STYLE 2.31 SET FILL AREA INTERIOR STYLE 2.31.1 FORTRAN calling sequence CALL GSFAIS (INTS) Input parameters: INTEGER INTS fill area interior style (GHOLLO, GSOLID, GPATTR, GHATCH) 2.31.2 Description The 'current fill area interior style' entry in the GKS state list is set to the value specified by the parameter. This value is used for the display of subsequent FILL AREA output primi- tives. The fill area interior style is used to determine in what style the area is filled and the possible values are: HOLLOW, SOLID, PATTERN and HATCH (see 4.4.6). If the requested interior style is not available on a workstation, HOLLOW is used on that workstation 2.31.3 Errors 8 GKS not in proper state; GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. -2-35- FUNCTIONAL DESCRIPTIONS SET LINETYPE 2.32 SET LINE TYPE 2.32.1 FORTRAN calling sequence CALL GSLN (LTYPE) Input parameters: INTEGER LTYPE linetype 2.32.2 Description The 'current linetype' entry in the GKS state list is set to the value specified by the parameter. This value is used for the display of subsequent POLYLINE output primitives. Linetype values produce linetypes as indicated: 1. solid line 2. dashed line 3. dotted line 4. dashed-dotted line 5-20. reserved for future standardization >=21. not used If the specified linetype is not available on a workstation, linetype 1 is used on that workstation. 2.32.3 Errors 8 GKS not in proper state; GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP 63 is equal to zero -2-36- FUNCTIONAL DESCRIPTIONS SET MARKERTYPE 2.33 SET MARKERTYPE 2.33.1 FORTRAN calling sequence CALL GSMK (MTYPE) Input parameters: INTEGER MTYPE marker type -2-37- FUNCTIONAL DESCRIPTIONS SET POLYLINE COLOR INDEX 2.34 SET POLYLINE COLOR INDEX 2.34.1 FORTRAN calling sequence CALL GSPLCI (COLI) Input parameters: INTEGER COLI polyline color index 2.34.2 Description The 'current polyline color index' entry in the GKS state list is set to the value specified by the parameter. This value is used for the display of subsequent POLYLINE output primitives. The color index is a pointer into the color tables of the workstations. If the specified color index is not present in a workstation color table, a workstation dependent color index is used on that workstation. 2.34.3 Errors 8 GKS not in proper state; GKS shall be in one of the states GKOP, WSOP, WSAC or SGOP. 85 Color index is less than zero. -2-38- FUNCTIONAL DESCRIPTIONS SET TEXT ALIGNMENT 2.35 SET TEXT ALIGNMENT 2.35.1 FORTRAN calling sequence CALL GSTXAL (TXALH, TXALV) Input parameters: INTEGER TXALH text alignment horizontal (GAHNOR, GALEFT, GACENT, GARITE) INTEGER TXALV text alignment vertical (GAVNOR, GATOP, GACAP, GAHALF, GABASE, GABOTT) 2.35.2 Description The 'current text alignment' entry in the GKS state list is set to the value specified by the parameter. This value is used when creating subsequent TEXT output primitives. Text alignment has two components: horizontal and vertical. 2.35.3 Errors 8 GKS not in proper state: GKS shall be in one of the states GKOP, WSOP, WSAC, or SGOP. -2-39- FUNCTIONAL DESCRIPTIONS SET TEXT COLOR INDEX 2.36 SET TEXT COLOR INDEX 2.36.1 FORTRAN calling sequence CALL GSTXCI (COLI) Input parameters: INTEGER COLI text color index -2-40- FUNCTIONAL DESCRIPTIONS SET VIEWPORT 2.37 SET VIEWPORT 2.37.1 FORTRAN calling sequence CALL GSVP (TNR, XMIN, XMAX, YMIN, YMAX) Input parameters: INTEGER TNR transformation number REAL XMIN, XMAX viewport limits in normalized device YMIN, YMAX coordinates -2-41- FUNCTIONAL DESCRIPTIONS SET WORKSTATION VIEWPORT 2.38 SET WORKSTATION VIEWPORT 2.38.1 FORTRAN calling sequence CALL GSWKVP (WKID, XMIN, XMAX, YMIN, YMAX) Input parameters: INTEGER WKID workstation identifier REAL XMIN, XMAX workstation viewport limits in device YMIN, YMAX coordinates -2-42- FUNCTIONAL DESCRIPTIONS SET WORKSTATION WINDOW 2.39 SET WORKSTATION WINDOW 2.39.1 FORTRAN calling sequence CALL GSWKWN (WKID, XMIN, XMAX, YMIN, YMAX) Input parameters: INTEGER WKID workstation identifier REAL XMIN, XMAX workstation window limits in nor- malized YMIN, YMAX device coordinates -2-43- FUNCTIONAL DESCRIPTIONS SET WINDOW 2.40 SET WINDOW 2.40.1 FORTRAN calling sequence CALL GSWN (TNR, XMIN, XMAX, YMIN, YMAX) Input parameters: INTEGER TNR transformation number REAL XMIN, XMAX, window limits in world coordinates YMIN, YMAX -2-44- FUNCTIONAL DESCRIPTIONS TEXT 2.41 TEXT 2.41.1 FORTRAN calling sequence CALL GTX (PX, PY, CHARS) Input parameters: INTEGER PX, PY text position in world coordinates CHARACTER*(*) CHARS string of characters 2.41.2 Description A character string is generated. The current values of the text attributes, as given by the GKS state list, are bound to the primitive. The text position is given in WC and transformed by the cur- rent normalization transformation. If, after the workstation transformation, the height or width of a character is zero, no error is generated and whether anything is drawn is workstation dependent. If the character string contains a control character (for example characters outside the range 2/0 to 7/14 inclusive in ISO 646), the effect is workstation dependent.Either error 101 is generated or some visual effect may be generated or the character may be ignored. Even if error 101 occurs, the character string is displayed on all active workstations which do not generate er- ror 101. NOTE Text is clipped in a way that depends on the text pre- cision as defined by the text font and precision cur- rently selected. -2-45- FUNCTIONAL DESCRIPTIONS TEXT 2.41.3 Errors 5 GKS not in proper state: GKS shall be either in the state WSAC or SGOP. 101 Invalid code in string. -2-46- FUNCTIONAL DESCRIPTIONS UPDATE WORKSTATION 2.42 UPDATE WORKSTATION 2.42.1 FORTRAN calling sequence CALL GUWK (WKID, REGFL) Input parameters: INTEGER WKID workstation identifier INTEGER REGFL update regeneration flag (GPOSTP, GPERFO) Functional Description 2.42.2 Description All deferred actions for the specified workstation are executed (without intermediate clearing of the display surface). If the regeneration flag is set to PERFORM and the 'new frame action necessary at update' entry in the workstation state list is YES, then the following actions are executed in the given sequence: 1. The display surface is cleared only if the 'display sur- face empty' entry in the workstation state list is NOTEMPTY. The entry is set to EMPTY. 2. If the 'workstation transformation update state' entry in the workstation state list is PENDING, the 'current workstation window' and 'current workstation viewport' entries in the workstation state list are assigned the values of the 'requested workstation window' and 'requested workstation viewport entries; the 'workstation transformation update state' entry is set to NOTPENDING. 3. The 'new frame action necessary at update' entry in the workstation state list is set to NO. NOTE If the regeneration flag is PERFORM, UPDATE WORKSTATION suspends the effect of SET DEFERRAL STATE. In that case, it is equivalent to the following sequence of functions: INQUIRE WORKSTATION STATE; save deferral state; SET DEFERRAL STATE (ASAP, ALLOWED); -2-47- FUNCTIONAL DESCRIPTIONS UPDATE WORKSTATION set deferral state to saved value; If the value of the 'new frame action necessary at update' entry is NO or the regeneration flag is SUPPRESS, UPDATE WORKSTA- TION merely initiates the transmission of blocked data. If the value of the entry 'new frame action necessary at update' is YES and the regeneration flag is PERFORM, UPDATE WORKSTATION behaves as REDRAW ALL SEGMENTS ON WORKSTATION (not supported in this im- plementation). The 'new frame action necessary at update' entry in the workstation state list is set to YES during deferred action generation if both of the following are true (see 4.5): 1. an action causing modification of the picture is ac- tually deferred on that workstation; 2. the workstation display surface does not allow modifica- tion of the image without redrawing the whole picture (for example, plotter, storage tube display). 2.42.3 Errors 7 GKS not in proper state: GKS shall be either in the state WSOP, WSAC or SGOP 20 Specified workstation identifier is invalid 25 Specified workstation is not open 33 Specified workstation is of category MI 35 Specified workstation is of category INPUT 36 Specified workstation is Workstation Independent Segment Storage -2-48- CHAPTER 3 USING GKS WITH RT-11 3.1 INCORPORATING GKS INTO FORTRAN SOURCE PROGRAMS GKS subroutines are accessed by FORTRAN subroutine calls. The calling sequence for each of the subroutines is shown in the chapter on Functional Descriptions. There is a general sequence in which GKS subroutine calls are made. The sequence is: CALL GOPKS (...) ! Open GKS CALL GOPWK (...) ! Open a workstation CALL GACWK (...) ! Activate the workstation . . ! Primitive and attribute . ! subroutine calls . CALL GDAWK (...) ! Deactivate the workstation CALL GCLWK (...) ! Close the work station CALL GCLKS (...) ! Close GKS This same general pattern is repeated in all programs that use GKS. Workstations may be activated and deactivated at any time, and more than one work station may be opened at one time. Many GKS functions make reference to enumerated data types. For example, four line types are mandated for GKS, that is they must be supported in all implementations. The four linetypes are solid, dashed, dotted and dash-dot. The FORTRAN calling conven- tion specifies an integer value for each of these line types (1, 2, 3 and 4 respectively). Definitions of all the GKS enumerated types can be found in the file GKENUM.FIN (listed in Appendix A). This file can be 'INCLUDE'ed in FORTRAN 77 programs, making it unnecessary to remember the correspondence between GKS scalars and their integer representations. For FORTRAN 66 programs, the PARAMETER state- ments would have to be replaced with equivalent DATA statements and the appropriate definitions would need to be edited into each file that calls GKS subroutines. -3-1- USING GKS WITH RT-11 Some GKS subroutines reference FORTRAN logical units. In particular, GOPKS (Open GKS) references a logical unit to be used for error reporting. GOPWK (Open Workstation) references a logi- cal unit to be used for graphical output to the associated workstation. The FORTRAN logical unit number supplied to these subroutines may be either OPEN for writing or CLOSED prior to the subroutine call. GKS checks to see if the unit is open. If it isn't, GKS will open the unit. NOTE This implementation of GKS does its own buffering of output streams. For this reason it only needs to know about RT-11 channel numbers. If a FORTRAN LUN is not open when a call is made to a GKS subroutine, an RT-11 channel will be requested from the runtime system and a file opened whose device name is the FORTRAN LUN, e.g. 11:OUTPUT.DAT. Thus the user can still assign FORTRAN LUNs to output devices at runtime. 3.2 LINKING PROGRAMS WITH GKS 3.2.1 Linking One Driver Four GKS modules are linked with the users program to build an executable image. The modules are the GKS subroutine library, GKS.OBJ; a driver table DRIVER.OBJ; the particular driver or drivers to be used, e.g. DRV745.OBJ; and the driver utility library DRVUTL.OBJ. Thus to link MYPROG with GKS and the HP7475 6 pen plotter driver the command would be: LINK MYPROG,GKS,DRIVER,DRV745,DRVUTL 3.2.2 Linking More than One Driver It is possible to link more than one driver with GKS. The procedure for doing this is as follows. 1. Change the entry point name of one of the drivers (it doesn't make any difference which one) from $CGID0 to $CGID1 and reassemble it. 2. Change the second entry in the subroutine vector list (shown below) to .WORD $CGID1 and reassemble it. -3-2- USING GKS WITH RT-11 3. Link the program as for the single driver case, except include both driver names in the LINK command GKS will accept up to eight drivers simultaneously. However if you actually try this you probably won't be able to do anything because there will be no memory space left! ----------------------------------------------------------------- ;**************************************************************** ;* Pointers to the workstation subroutine vector lists. Entries * ;* with a -1 are unused. * ;**************************************************************** .PSECT G$$WSV,RW,D,GBL,REL,OVR WSSBVC::.WORD $CGID0 ; Device driver number 1 .WORD -1 ; Device driver number 2 .WORD -1 ; Device driver number 3 .WORD -1 ; Device driver number 4 .WORD -1 ; Device driver number 5 .WORD -1 ; Device driver number 6 .WORD -1 ; Device driver number 7 .WORD -1 ; Device driver number 8 .END ---------------------------------------------------------------- Source Code for DRIVER.OBJ 3.3 RUNNING PROGRAMS THAT USE GKS Programs that make calls to GKS subroutines run just like any other RT-11 program. However, it is the user's responsibil- ity to make the logical connection between FORTRAN logical units used by the program and RT-11 devices. Thus the sequence to run a program that was linked with the Visual 550 device driver and which specified output to that device on FORTRAN logical unit 10 would be: .ASSIGN TT: 10 .RUN MYPROG -3-3- APPENDIX A GKS ENUMERATION TYPES All the enumeration types of GKS are mapped to FORTRAN IN- TEGERs. The correspondence between GKS scalars and FORTRAN IN- TEGERs is shown below in a list of symbolic FORTRAN constants which may be included in any application program. These con- stants are defines in the file GKENUM.FIN. This file should be 'INCLUDE'ed in any program that makes subroutine calls to GKS functions. C C Aspect source bundled C Bundled Individual INTEGER GBUNDL, GINDIV PARAMETER (GBUNDL=0, GINDIV=1) C C Clear control flag C conditionally, always INTEGER GCONDI, GALWAY PARAMETER (GCONDI=0, GALWAY=1) C C Clipping indicator C noclip, clip INTEGER GNCLIP, GCLIP PARAMETER (GNCLIP=0, GCLIP=1) C C Colour available C monochrome, colour INTEGER GMONOC, GCOLOR PARAMETER (GMONOC=0, GCOLOR=1) C C Coordinate switch C WC, NDC INTEGER GWC, GNDC PARAMETER (GWC=0, GNDC=1) C C Deferral mode C ASAP, BNIG, BNIL, ASTI INTEGER GASAP, GBNIG, GBNIL, GASTI PARAMETER (GASAP=0, GBNIG=1, GBNIL=2, GASTI=3) C C Detectability -A-1- GKS ENUMERATION TYPES C undetectable, detectable INTEGER GUNDET, GDETEC PARAMETER (GUNDET=0, GDETEC=1) C C Device coordinate units C metres, other INTEGER GMETRE, GOTHU PARAMETER (GMETRE=0, GOTHU=1) C C Display surface empty C notempty, empty INTEGER GNEMPT, GEMPTY PARAMETER (GNEMPT=0, GEMPTY=1) C C Dynamic modification C IRG, IMM INTEGER GIRG, GIMM PARAMETER (GIRG=0, GIMM=1) C C Echo switch C noecho, echo INTEGER GNECHO, GECHO PARAMETER (GNECHO=0, GECHO=1) C C Fill area interior style C hollow, solid, pattern, hatch INTEGER GHOLLO, GSOLID, GPATTR, GHATCH PARAMETER (GHOLLO=0, GSOLID=1, GPATTR=2, GHATCH=3) C C Highlighting C normal, highlighted INTEGER GNORML, GHILIT PARAMETER (GNORML=0, GHILIT=1) C C Input device status C none, ok, nopick, nochoice INTEGER GNONE, GOK, GNPICK, GNCHOI PARAMETER (GNONE=0, GOK=1, GNPICK=2, GNCHOI=3) C C Input class C none, locator, stroke, valuator, C choice, pick, string INTEGER GNCLAS, GLOCAT, GSTROK, GVALUA, + GCHOIC, GPICK, GSTRIN PARAMETER (GNCLAS=0, GLOCAT=1, GSTROK=2, GVALUA=3, + GCHOIC=4, GPICK=5, GSTRIN=6) C C Implicit regeneration mode C suppressed, allowed INTEGER GSUPPD, GALLOW PARAMETER (GSUPPD=0, GALLOW=1) C C Level of GKS C Lma, Lmb, Lmc, L0a, L0b, C L0c, L1a, L1b, L1c, L2a, -A-2- GKS ENUMERATION TYPES C L2b, L2c INTEGER GLMA, GLMB, GLMC, GL0A, GL0B, + GL0C, GL1A, GL1B, GL1C, GL2A, + GL2B, GL2C PARAMETER (GLMA=-3, GLMB=-2, GLMC=-1, GL0A=0, GL0B=1, + GL0C=2, GL1A=3, GL1B=4, GL1C=5, GL2A=6, + GL2B=7, GL2C=8) C C New frame action necessary C no, yes INTEGER GNO, GYES PARAMETER (GNO=0, GYES=1) C C Operating mode C request, sample, event INTEGER GREQU, GSAMPL, GEVENT PARAMETER (GREQU=0, GSAMPL=1, GEVENT=2) C C Operating state values C GKCL, GKOP, GWSOP, GWSAC, GSGOP INTEGER GKCL, GKOP, GWSOP, GWSAC, GSGOP PARAMETER (GKCL=0, GKOP=1, GWSOP=2, GWSAC=3, GSGOP=4) C C Presence of invalid values C absent, present INTEGER GABSNT, GPRSNT PARAMETER (GABSNT=0, GPRSNT=1) C C Regeneration flag C postpone, perform INTEGER GPOSTP, GPERFO PARAMETER (GPOSTP=0, GPERFO=1) C C Relative input priority C higher, lower INTEGER GHIGHR, GLOWER PARAMETER (GHIGHR=0, GLOWER=1) C C Simultaneous events flag. C nomore, more INTEGER GNMORE, GMORE PARAMETER (GNMORE=0, GMORE=1) C C Text Alignment Horizontal C Normal Left Center Right INTEGER GAHNOR, GALEFT, GACENT, GARITE PARAMETER (GAHNOR=0, GALEFT=1, GACENT=2, GARITE=3) C C Text Alignment Vertical C Normal, Top, Cap, Half, Base, C Bottom INTEGER GAVNOR, GATOP, GACAP, GAHALF, GABASE, + GABOTT PARAMETER (GAVNOR=0, GATOP=1, GACAP=2, GAHALF=3, -A-3- GKS ENUMERATION TYPES GABASE=4, + GABOTT=5) C C Text path C right left, up, down INTEGER GRIGHT, GLEFT, GUP, GDOWN PARAMETER (GRIGHT=0, GLEFT=1, GUP=2, GDOWN=3) C C Text precision C string, character, stroke INTEGER GSTRP, GCHARP, GSTRKP PARAMETER (GSTRP=0, GCHARP=1, GSTRKP=2) C C Type of returned values C set realized INTEGER GSET, GREALI PARAMETER (GSET=0, GREALI=1) C C Update state C notpending, pending INTEGER GNPEND, GPEND PARAMETER (GNPEND=0, GPEND=1) C C Vector/Raster/Other type C vector, raster, other INTEGER GVECTR, GRASTR, GOTHWK PARAMETER (GVECTR=0, GRASTR=1, GOTHWK=2) C C Visibility C invisible, visible INTEGER GINVIS, GVISI PARAMETER (GINVIS=0, GVISI=1) C C Workstation category C output, input, outin, wiss, mo, C mi INTEGER GOUTPT, GINPUT, GOUTIN, GWISS, GMO, + GMI PARAMETER (GOUTPT=0, GINPUT=1, GOUTIN=2, GWISS=3, GMO=4, + GMI=5) C C Workstation state C inactive, active INTEGER GINACT, GACTIV PARAMETER (GINACT=0, GACTIV=1) C C List of GDP attributes C polyline attribute, polymarker attribute, text C attribute, fill area attribute INTEGER GPLATT, GPMATT, GTXATT, GFAATT PARAMETER (GPLATT=0, GPMATT=1, GTXATT=2, GFAATT=3) C -A-4- GKS ENUMERATION TYPES C Line type C solid, dash, dot, dash-dot INTEGER GLSOLI, GLDASH, GLDOT, GLDASD PARAMETER (GLSOLI=1, GLDASH=2, GLDOT=3, GLDASD=4) C C Marker type C '.', '+', '*', 'o', C 'x' INTEGER GPOINT, GPLUS, GAST, GOMARK, + GXMARK PARAMETER (GPOINT=1, GPLUS=2, GAST=3, GOMARK=4, + GXMARK=5) C C Attribute control flag C current, specified INTEGER GCURNT, GSPEC PARAMETER (GCURNT=0, GSPEC=1) C C Polyline/Fill Area control flag C polyline, fill area INTEGER GPLINE, GFILLA PARAMETER (GPLINE=0, GFILLA=1) C C Initial choice prompt flag C off on INTEGER GPROFF, GPRON PARAMETER (GPROFF=0, GPRON=1) -A-5- INDEX ACTIVATE WORKSTATION . . . . . . . . . . . . . . . . 1-5, 2-2 ANSI . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 ATTRIBUTES . . . . . . . . . . . . . . . . . . . . . . . . 1-2 CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 CHARACTER HEIGHT . . . . . . . . . . . . . . . . . 2-12, 2-30 CHARACTER UP VECTOR . . . . . . . . . . . . . . . . 2-13, 2-31 CLEAR WORKSTATION . . . . . . . . . . . . . . . . . . . . . 2-4 CLIP INDICATOR . . . . . . . . . . . . . . . . . . . . . . 1-7 CLIPPING . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 CLIPPING INDICATOR . . . . . . . . . . . . . . . . 2-14, 2-32 CLOSE GKS . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 CLOSE WORKSTATION . . . . . . . . . . . . . . . . . . 1-5, 2-6 COLOR FACILITIES . . . . . . . . . . . . . . . . . . . . 2-11 COLOR REPRESENTATION . . . . . . . . . . . . . . . . . . 2-16 COORDINATE SYSTEMS . . . . . . . . . . . . . . . . . . . . 1-6 DEACTIVATE WORKSTATION . . . . . . . . . . . . . . . . . . 2-7 DECUS DEVICE DRIVERS . . . . . . . . . . . . . . . . . . . 1-1, 3-2 ENUMERATION TYPES . . . . . . . . . . . . . . . . . . . . . A-1 FILL AREA . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 FILL AREA COLOR INDEX . . . . . . . . . . . . . . . 2-18, 2-34 FILL AREA INTERIOR STYLE . . . . . . . . . . . . . 2-19, 2-35 FORTRAN LUN . . . . . . . . . . . . . . . . . . . . . . . . 3-2 GACWK . . . . . . . . . . . . . . . . . . . . . . . . 2-2, 3-1 GCLKS . . . . . . . . . . . . . . . . . . . . . . . . 2-3, 3-1 GCLRWK . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 GCLWK . . . . . . . . . . . . . . . . . . . . . . . . 2-6, 3-1 GDAWK . . . . . . . . . . . . . . . . . . . . . . . . 2-7, 3-1 GKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 GOPKS . . . . . . . . . . . . . . . . . . . . . . 2-8, 3-1, 3-2 GOPWK . . . . . . . . . . . . . . . . . . . . . . 2-9, 3-1, 3-2 GPM . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 GQCF . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 GQCHH . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 GQCHUP . . . . . . . . . . . . . . . . . . . . . . . . . 2-13 GQCLIP . . . . . . . . . . . . . . . . . . . . . . . . . 2-14 GQCNTN . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 GQCR . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16 GQFACI . . . . . . . . . . . . . . . . . . . . . . . . . 2-18 GQFAIS . . . . . . . . . . . . . . . . . . . . . . . . . 2-19 GQLN . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20 GQLVKS . . . . . . . . . . . . . . . . . . . . . . . . . 2-21 GQMK . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22 GQNT . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23 GQPLCI . . . . . . . . . . . . . . . . . . . . . . . . . 2-24 GQPMCI . . . . . . . . . . . . . . . . . . . . . . . . . 2-25 GQTXAL . . . . . . . . . . . . . . . . . . . . . . . . . 2-26 GQWKC . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27 -X-1- GQWKT . . . . . . . . . . . . . . . . . . . . . . . . . . 2-28 GSCHH . . . . . . . . . . . . . . . . . . . . . . . . . . 2-30 GSCHUP . . . . . . . . . . . . . . . . . . . . . . . . . 2-31 GSCLIP . . . . . . . . . . . . . . . . . . . . . . . . . 2-32 GSELNT . . . . . . . . . . . . . . . . . . . . . . . . . 2-33 GSFACI . . . . . . . . . . . . . . . . . . . . . . . . . 2-34 GSFAIS . . . . . . . . . . . . . . . . . . . . . . . . . 2-35 GSLN . . . . . . . . . . . . . . . . . . . . . . . . . . 2-36 GSMK . . . . . . . . . . . . . . . . . . . . . . . . . . 2-37 GSPLCI . . . . . . . . . . . . . . . . . . . . . . . . . 2-38 GSTXAL . . . . . . . . . . . . . . . . . . . . . . . . . 2-39 GSTXCI . . . . . . . . . . . . . . . . . . . . . . . . . 2-40 GSVP . . . . . . . . . . . . . . . . . . . . . . . . . . 2-41 GSWKVP . . . . . . . . . . . . . . . . . . . . . . . . . 2-42 GSWKWN . . . . . . . . . . . . . . . . . . . . . . . . . 2-43 GSWN . . . . . . . . . . . . . . . . . . . . . . . . . . 2-44 GTX . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-45 GUWK . . . . . . . . . . . . . . . . . . . . . . . . . . 2-47 HP7475 INQUIRY FUNCTIONS . . . . . . . . . . . . . . . . . . . . . 1-3 ISO . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 LEVEL OF GKS . . . . . . . . . . . . . . . . . . . . . . 2-21 LINETYPE . . . . . . . . . . . . . . . . . . . . . . 2-20, 3-1 NORMALIZATION TRANSFORMATION . . . . . . . . . . . 2-23, 2-33 NORMALIZATION TRANSFORMATION NUMBER . . . . . . . . . . . 2-15 OPEN . . . . . . . . . . . . . . . . . . . . . . . . 2-8, 2-9 OPEN WORKSTATION . . . . . . . . . . . . . . . . . . . . . 1-5 OUTPUT PRIMITIVES . . . . . . . . . . . . . . . . . . . . . 1-3 POLYLINE . . . . . . . . . . . . . . . . 1-1, 1-3, 2-36, 2-38 POLYLINE COLOR INDEX . . . . . . . . . . . . . . . . . . 2-24 POLYMARKER . . . . . . . . . . . . . . . . . . 1-1, 1-4, 2-10 POLYMARKER COLOR INDEX . . . . . . . . . . . . . . . . . 2-25 POLYMARKER INDEX . . . . . . . . . . . . . . . . . . . . 2-22 PRIMITIVE ATTRIBUTES . . . . . . . . . . . . . . . . . . . 1-4 PRIMITIVES . . . . . . . . . . . . . . . . . . . . . . . . 1-2 SELECT NORMALIZATION TRANSFORMATION . . . . . . . . . . . . 1-7 SET LINETYPE . . . . . . . . . . . . . . . . . . . . . . 2-36 SET MARKERTYPE . . . . . . . . . . . . . . . . . . . . . 2-37 SET POLYLINE COLOR INDEX . . . . . . . . . . . . . . . . 2-38 SET TEXT ALIGNMENT . . . . . . . . . . . . . . . . . . . 2-39 SET TEXT COLOR INDEX . . . . . . . . . . . . . . . . . . 2-40 SET VIEWPORT . . . . . . . . . . . . . . . . . . . . . . 2-41 SET WINDOW . . . . . . . . . . . . . . . . . . . . . . . 2-44 TEKTRONICS 4107 . . . . . . . . . . . . . . . . . . . . . . 1-1 TEXT . . . . . . . . . . . . . . . 1-1, 1-4, 2-39, 2-40, 2-45 TEXT ALIGNMENT . . . . . . . . . . . . . . . . . . . . . 2-26 TRANSFORMATIONS . . . . . . . . . . . . . . . . . . . . . . 1-6 -X-2- UPDATE WORKSTATION . . . . . . . . . . . . . . . . . . . 2-47 VIEWPORT . . . . . . . . . . . . . . . . . . . . . . . . 2-41 VISUAL 550 . . . . . . . . . . . . . . . . . . . . . . . . 1-1 WINDOW . . . . . . . . . . . . . . . . . . . . . . . . . 2-44 WORKSTATION . . . . . . . . . . . . . . . . . . . . . 2-9, 2-47 WORKSTATION CONNECTION . . . . . . . . . . . . . . . . . 2-27 WORKSTATION TRANSFORMATION . . . . . . . . . . . . . . . 2-28 WORKSTATION TRANSFORMATIONS . . . . . . . . . . . . . . . . 1-7 WORKSTATION TYPE . . . . . . . . . . . . . . . . . . . . 2-27 WORKSTATION VIEWPORT . . . . . . . . . . . . . . . . . . 2-42 WORKSTATION WINDOW . . . . . . . . . . . . . . . . . . . 2-43 WORKSTATIONS . . . . . . . . . . . . . . . . . . . . . . . 1-5 X3H3 . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 -X-3-