GKS Reference Manual - Atossupport.bull.com/ols/product/system/gcos7/gcos7... · GKS defines a language-independent nucleus of a graphic system. For integration into a programming

GKS

Reference Manual

DPS

7000/XTA

NO

VASC

ALE

7000

Languages: General

REFERENCE47 A2 40UL 01

DPS7000/XTANOVASCALE 7000

GKSReference Manual

Languages: General

July 1987

BULL CEDOC

357 AVENUE PATTON

B.P.20845

49008 ANGERS CEDEX 01

FRANCE

REFERENCE47 A2 40UL 01

The following copyright notice protects this book under Copyright laws which prohibit such actions as, but notlimited to, copying, distributing, modifying, and making derivative works.

Copyright Bull SAS 1987

Printed in France

Suggestions and criticisms concerning the form, content, and presentation of thisbook are invited. A form is provided at the end of this book for this purpose.

To order additional copies of this book or other Bull Technical Publications, youare invited to use the Ordering Form also provided at the end of this book.

Trademarks and Acknowledgements

We acknowledge the right of proprietors of trademarks mentioned in this book.

Intel® and Itanium® are registered trademarks of Intel Corporation.

Windows® and Microsoft® software are registered trademarks of Microsoft Corporation.

UNIX® is a registered trademark in the United States of America and other countries licensed exclusively throughthe Open Group.

Linux® is a registered trademark of Linus Torvalds.

The information in this document is subject to change without notice. Bull will not be liable for errors containedherein, or for incidental or consequential damages in connection with the use of this material.

47 A2 40UL Rev01 iii

Preface

OBJECTIVES

This manual describes a set of functions (GKS) for computer graphics programmingunder GCOS7 (i.e. IOF and TDS).

INTENDED READERS

Computer graphics programmers.

STRUCTURE OF THIS MANUAL

Section 1 Gives an overview of the scope and field of application of GKS.Section 2 Contains definitions of GKS terms.Section 3 Considers functional aspect of GKS and graphical I/O devices.Section 4 Discusses general aspects of FORTRAN and COBOL interfaces.Section 5 Lists the GKS functions, giving the states in which they may be

used, the corresponding FORTRAN and COBOL subroutine callsand their input/output parameters.

Section 6 Lists the contents of GKS data structures.Section 7 Describes how to transfer GKS grahics between a user program

and an indexed UFAS file.Section 8 Explains how to use GKS on a BULL PRT 1220Appendix A Lists GKS functions, with page numbers.Appendix B Lists the error codes and messages.Appendix C Summarizes all the GKS functions.Appendix D Contains sample programs.

GKS Reference Manual

iv 47 A2 40UL Rev01

ASSOCIATED DOCUMENTS

For further information on associated subjects, the following manuals can be consulted :

TDS Programmer's Manual................................................................................47A203UTFORTRAN 77 Reference Manual ......................................................................47A215ULIOF Programmer's Manual ................................................................................. 47A205UJCOBOL 74 Reference Manual ...........................................................................47A201UL

47 A2 40UL Rev01 v

Table of Contents

1. Scope and Field of Application ..................................................................... 1-1

2. Definitions .............................................................................................................. 2-1

3. The Graphical Kernel System ........................................................................ 3-1

3.1 INTRODUCTION......................................................................................................... 3-1

3.2 CONCEPTS ................................................................................................................ 3-2

3.3 GRAPHICAL OUTPUT ............................................................................................... 3-4

3.3.1 Output Primitives ...................................................................................................... 3-43.3.2 Generalized Drawing Primitive ................................................................................ 3-43.3.3 Output Primitive Attributes ...................................................................................... 3-53.3.4 Polyline Attributes ..................................................................................................... 3-83.3.5 Polymarker Attributes ............................................................................................... 3-83.3.6 Text Attributes ........................................................................................................... 3-93.3.7 Fill Area Attributes .................................................................................................... 3-173.3.8 Cell Array Attributes .................................................................................................. 3-183.3.9 Generalized Drawing Primitive Attributes .............................................................. 3-193.3.10 Colour ......................................................................................................................... 3-193.3.11 Workstation Dependent Bundle Table .................................................................... 3-203.3.11.1 ANDERSON JACOBSON Bundle Tables ................................................................... 3-203.3.11.2 TEKTRONIX 4105 Bundle Tables............................................................................... 3-22

3.4 WORKSTATIONS ....................................................................................................... 3-26

3.4.1 Workstation Characteristics .................................................................................... 3-263.4.2 Selecting a Workstation ........................................................................................... 3-27

3.5 COORDINATE SYSTEMS AND TRANSFORMATIONS ........................................... 3-28


vi 47 A2 40UL Rev01

3.5.1 Normalization Transformation ................................................................................. 3-283.5.2 Clipping ...................................................................................................................... 3-293.5.3 Workstation Transformations .................................................................................. 3-29

3.6 STATES OF GKS AND INQUIRY FUNCTIONS ........................................................ 3-31

3.6.1 Description Of States ................................................................................................ 3-313.6.2 Inquiry Function ........................................................................................................ 3-31

3.7 ERROR HANDLING ................................................................................................... 3-33

4. Language Bindings ............................................................................................ 4-1

4.1 INTRODUCTION......................................................................................................... 4-1

4.2 ENUMERATION TYPES............................................................................................. 4-1

4.3 GKS FUNCTION IDENTIFICATION ........................................................................... 4-3

4.4 FORTRAN INTERFACE ............................................................................................. 4-4

4.4.1 Introduction ............................................................................................................... 4-44.4.2 Representation of Cell Array and Pixel Array ......................................................... 4-4

4.5 COBOL INTERFACE .................................................................................................. 4-6

4.5.1 Introduction ............................................................................................................... 4-64.5.2 Data Formats ............................................................................................................. 4-74.5.3 Open GKS .................................................................................................................. 4-74.5.4 Text Functions ........................................................................................................... 4-84.5.5 Error Procedures ....................................................................................................... 4-94.5.6 Cell Array And Pixel Array Functions ...................................................................... 4-94.5.7 COBOL Interface Under TDS .................................................................................... 4-104.5.7.1 Introduction.................................................................................................................. 4-104.5.7.2 TDS Generation Program ........................................................................................... 4-104.5.7.3 Message...................................................................................................................... 4-11

5. The GKS Function Interface ........................................................................... 5-1

5.1 CONTROL FUNCTIONS ............................................................................................ 5-1

5.2 OUTPUT FUNCTIONS ............................................................................................... 5-7

Table of Contents

47 A2 40UL Rev01 vii

5.3 OUTPUT ATTRIBUTES .............................................................................................. 5-15

5.3.1 Workstation Independent Primitive Attributes ....................................................... 5-155.3.2 Workstation attributes (representation) ................................................................. 5-30

5.4 TRANSFORMATION FUNCTIONS ............................................................................ 5-31

5.4.1 Normalization Transformation ................................................................................. 5-315.4.2 Workstation Transformation .................................................................................... 5-33

5.5 METAFILE FUNCTIONS ............................................................................................ 5-35

5.6 INQUIRY FUNCTIONS ............................................................................................... 5-37

5.6.1 INTRODUCTION......................................................................................................... 5-375.6.2 Inquiry Function for Operating State Value ............................................................ 5-375.6.3 Inquiry Functions for GKS Description Table ........................................................ 5-375.6.4 Inquiry Functions for GKS State List ...................................................................... 5-405.6.5 Inquiry Functions for Workstation State List ......................................................... 5-605.6.6 Inquiry Functions for Workstation Description Table ........................................... 5-685.6.7 Pixel Inquiries ............................................................................................................ 5-82

5.7 ERROR HANDLING ................................................................................................... 5-85

6. GKS Data Structures ......................................................................................... 6-1

6.1 NOTATION AND DATA TYPES ................................................................................. 6-1

6.2 OPERATING STATE .................................................................................................. 6-3

6.3 GKS DESCRIPTION TABLE ...................................................................................... 6-3

6.4 GKS STATE LIST ....................................................................................................... 6-4

6.5 WORKSTATION STATE LIST ................................................................................... 6-5

6.6 WORKSTATION DESCRIPTION TABLE .................................................................. 6-6

7. GKS Metafile .......................................................................................................... 7-1

7.1 INTRODUCTION......................................................................................................... 7-1


viii 47 A2 40UL Rev01

7.2 PREPARATION AND ACTIVATION OF A METAFILE .............................................. 7-2

7.3 PICTURE CONCEPTS ............................................................................................... 7-7

7.4 PICTURE MGT PRIMITIVES ...................................................................................... 7-9

7.5 GRAPHICAL ITEM CONCEPTS ................................................................................ 7-17

7.6 LIST OF GRAPHICAL ITEMS .................................................................................... 7-18

7.7 ITEM MGT PRIMITIVES ............................................................................................. 7-19

7.8 SET AND INQUIRY PRIMITIVES ............................................................................... 7-24

7.9 PROGRAMMING RULES IN TDS .............................................................................. 7-24

7.10 A SIMPLE EXAMPLE ................................................................................................. 7-25

7.11 NUMBER OF PICTURES ........................................................................................... 7-27

8. GKS on the Bull PRT 1220 .............................................................................. 8-1

8.1 INTRODUCTION......................................................................................................... 8-1

8.2 THE BIT MAP ............................................................................................................. 8-2

8.3 OUTPUT PRIMITIVE ATTRIBUTES .......................................................................... 8-4

8.4 BUNDLE TABLES ...................................................................................................... 8-7

8.5 ERROR LOGGING ..................................................................................................... 8-8

Table of Contents

47 A2 40UL Rev01 ix

Appendices

A. Function Lists ....................................................................................................... A-1

B. Error Lists .............................................................................................................. B-1

C. GKS Function Summary .................................................................................. C-1

C.1 CONTROL FUNCTIONS ............................................................................................ C-1

C.2 OUTPUT FUNCTIONS ............................................................................................... C-2

C.3 OUTPUT ATTRIBUTES .............................................................................................. C-3

C.3.1 Workstation Independent Primitive Attributes ....................................................... C-3C.3.2 Workstation Attributes (representations) ............................................................... C-4

C.4 TRANSFORMATION FUNCTIONS ............................................................................ C-5

C.4.1 Normalization Transformation ................................................................................. C-5C.4.2 Workstation Transformation .................................................................................... C-5

C.5 METAFILE FUNCTIONS ............................................................................................ C-6

C.6 INQUIRY FUNCTIONS ............................................................................................... C-6

C.7 ERROR HANDLING ................................................................................................... C-6

D. Sample Programs ............................................................................................... D-1


x 47 A2 40UL Rev01

Table of Contents

47 A2 40UL Rev01 xi

Illustrations

Figures

3-1 Layer model of GKS.................................................................................................... 3-13-2 Font description coordinate system ............................................................................ 3-113-3 Effects of changes in geometric text aspects (change aspects are underlined)......... 3-143-4 Effects of changes in non-geometric text aspects

(changed aspects are underlined)............................................................................... 3-153-5 Effects of combined changes in text aspects (changed aspects are underlined) ....... 3-153-6 Hatch index for ANDERSON JACOBSON 832 and 833............................................. 3-183-7 Possible Transitions between Operating states .......................................................... 3-323-8 TREATMENT of ERRORS.......................................................................................... 3-355-1 Examples of FILL AREA clipping ................................................................................ 5-95-2 Area inside a polygon.................................................................................................. 5-105-3 Examples of replies to INQUIRE TEXT EXTENT with different text attributes ........... 5-658-1 Hatch index for PRT 1220........................................................................................... 8-5

Tables

4-1 Enumeration type ........................................................................................................ 4-14-2 Function Identification ................................................................................................. 4-3


xii 47 A2 40UL Rev01

47 A2 40UL Rev01 1-1

1. Scope and Field of Application

This document specifies a set of functions for computer graphics programming that canbe used under IOF and TDS. It is a basic graphics system for applications that producecomputer generated two dimensional pictures on line graphics or raster graphics outputdevices. A fundamental concept in GKS is the workstation, consisting of a number ofinput devices and a single output device. The application program is allowed to adapt itsbehaviour to a workstation to make best use of workstation capabilities.

This document includes all the functions of level O-a of GKS. At this level, metafilefunctions are note needed. These functions exist, but return appropriate error messages.

GKS defines a language-independent nucleus of a graphic system. For integration into aprogramming language, GKS is embedded in a language-dependant layer obeying theparticular conventions of that language.

In this document, we also present the language interface for FORTRAN complying withthe international standard FORTRAN interface of GKS 7.2 ; the COBOL interface isbased on the FORTRAN interface with some modifications.

FORTRAN programs are not allowed under TDS. The array of possibilities is :

FORTRAN COBOLIOF Allowed AllowedTDS Not Allowed Allowed

A driver exists for four types of terminal :

• Anderson Jacobson 832

• Anderson Jacobson 833

• Tektronix 4105

• Bull PRT 1220


1-2 47 A2 40UL Rev01

47 A2 40UL Rev01 2-1

2. Definitions

This section gives definitions of important terms in the Graphical Kernel System (GKS).As far as possible, commonly accepted graphics terminology is used.

Aspects of primitives:

Ways in which the appearance of a primitive can vary. Some aspects are controlleddirectly by primitive attributes ; some are controlled indirectly through a bundle table.

Attribute:

A particular property, for example character height, that applies to a display element(output primitive). Note that, in GKS, some properties of workstations are calledworkstation attributes.

Bundle index:

An index into a bundle table for a particular output primitive. It defines the workstationdependent aspects of the primitive.

Bundle table:

A workstation dependent table associated with a particular output primitive. Entries in thetable specify all the workstation dependent aspects of a primitive. In GKS, bundle tablesexist for the following output primitives : polyline, polymarker, text and fill area.

Cell array:

A GKS output primitive consisting of a rectangular grid of equal size rectangular cells,each having a single colour. Note that these cells do not necessarily map one-to-onewith pixels.

Clipping:

Removing parts of display elements that lie outside a given boundary, usually a windowor viewport.


2-2 47 A2 40UL Rev01

Colour table:

A workstation dependent table, in which the entries specify the values of the red, greenand blue intensities defining a particular colour.

Coordinate graphics / line graphics:

Computer graphics in which display images are generated from display commands andcoordinate data.

Device coordinate (DC):

A coordinate expressed in a coordinate system that is device dependent.

Device driver:

The device dependent part of GKS implementation intended to support a graphicsdevice. The device driver generates device dependent output and handles devicedependent interaction.

Device space:

The space defined by the addressable points of a display device.

Display device / graphics device:

A device (for example refresh display, storage tube display, plotter) on which displayimages can be represented.

Display element:

A basic graphic element that can be used to construct a display image.

Display image / picture:

A collection of display elements that are represented together at any one time on adisplay surface.

Display space:

That portion of the device space corresponding to the area available for displayingimages.

Display surface / view surface:

The medium on which display images may appear in a display device.

Definitions

47 A2 40UL Rev01 2-3

Escape:

A function in GKS used to access implementation or device dependent features, otherthan for the generation of graphical output, which are not otherwise addressed by GKS.

Fill area:

A GKS output primitive consisting of a polygon (closed boundary) which may be hollowor may be filled with a uniform colour, a pattern, or a hatch style.

Fill area bundle table:

A table associating specific values for all workstation dependent aspects of a fill areaprimitive with a fill area bundle index. In GKS, this table contains entries consisting ofinterior style, style index, and colour index.

Generalized Drawing Primitive (GDP):

An output primitive used to address special geometrical workstation capabilities such ascurve drawing.

GKS level:

Two values in the range 0 to 2 and a to c which together define the set of functionalcapabilities provided by a specific GKS implementation.

GKS metafile (GKSM):

A sequential file that can be written or read by GKS : used for long-term storage (and fortransmission and transfer) of graphical information.

Implementation mandatory:

Implementation mandatory describes a property that must be realized identically on allworkstations of all implementations of the standard.

Marker:

A glyph with a specified appearance which is used to identify a particular location.

Normalization, viewing or window-to-viewport transformation:

A transformation that maps the boundary and interior of a window to the boundary andinterior of a viewport. Note that, in GKS, this transformation maps positions in worldcoordinates to normalized device coordinates.


2-4 47 A2 40UL Rev01

Normalized device coordinates (NDC):

A coordinate specified in a device independent intermediate coordinate system,normalized to some range, typically 0 to 1. Note that during an intermediate state inGKS, the coordinates may lie outside the defined range, but that associated clippinginformation ensures that the output does not exceed the coordinate range [0,1]x[0,1].

Output primitive / graphic primitive:

A display element. Output primitives in GKS are POLYLINE, POLYMARKER, TEXT,FILL AREA, CELL ARRAY, and GENERALIZED DRAWING PRIMITIVE.

Pixel / picture element:

The smallest element of a display surface that can be independently assigned a colouror intensity.

Polyline:

A GKS output primitive consisting of a set of connected lines.

Polyline bundle table:

A table associating specific values for all workstation dependent aspects of a polylineprimitive with a polyline bundle index. In GKS, this table contains entries consisting oflinetype, linewidth scale factor, and colour index.

Polymarker:

A GKS output primitive consisting of a set of locations, each to be indicated by a marker.

Polymarker bundle table:

A table associating specific values for all workstation dependent aspects of a polymarkerprimitive with a polymarker bundle index. In GKS, this table contains entries consisting ofmarker type, marker size scale factor and colour index.

Primitive attribute:

Primitive attribute values (for output primitives) are selected by the application in aworkstation independent manner, but can have workstation dependent effects.

Raster graphics:

Computer graphics in which a display image is composed of an array of pixels arrangedin rows and columns.

Definitions

47 A2 40UL Rev01 2-5

Text:

A GKS output primitive consisting of a character string.

Text bundle table:

A table associating specific values for all workstation dependent aspects of a textprimitive with a text bundle index. In GKS, this table contains entries consisting of textfont and precision, character expansion factor, character spacing and colour index.

Text font and precision:

In GKS these determine the shape of the characters being output on a particularworkstation. In addition, the precision describes the fidelity with which the other textaspects match those requested by an application program. In order of increasing fidelity,the precisions are : STRING, CHAR AND STROKE.

Viewport:

Part of the normalized device coordinate space (specified by an application program.Note that, in GKS, this definition is restricted to a rectangular region of normalized devicecoordinate space used in the definition of the normalization transformation.

Window:

A predefined part of a virtual space. Note that, in GKS, this definition is restricted to arectangular region of the world coordinate space used for the definition of thenormalization transformation.

Workstation:

GKS is based on the concept of abstract graphical workstations, which provide thelogical interface through which the application program controls physical devices.

Workstation mandatory:

Workstation mandatory describes a property that must be realized identically on allworkstations of a standard implementation.

Workstation transformation:

A transformation that maps the boundary and interior of a workstation window into theboundary and interior of a workstation viewport (part of display space), preserving aspectratio. Note that, in GKS, this transformation maps positions in normalized devicecoordinates to device coordinates. The effect of preserving the aspect ratio is to preventthe interior of the workstation window from mapping onto the whole of the workstationviewport.


2-6 47 A2 40UL Rev01

Workstation viewport:

A portion of display space currently selected for output of graphics.

Workstation window:

A rectangular region within the normalized device coordinate system which isrepresented on a display space.

World coordinates (WC):

A device independent Cartesian coordinate system used by the application program forspecifying graphical input and output.

47 A2 40UL Rev01 3-1

3. The Graphical Kernel System

3.1 INTRODUCTION

The Graphical Kernel System (GKS) provides a functional interface between anapplication program and a configuration of graphical input and output devices. Thefunctional interface contains all basic functions for interactive and non-interactivegraphics on a wide variety of graphics equipment.

The interface is at such a level of abstraction that hardware peculiarities are shieldedfrom the application program. As a result a simplified interface presenting uniform outputprimitives (POLYLINE, POLYMARKER, TEXT, FILL AREA, CELL ARRAY,GENERALIZED DRAWING PRIMITIVES) is obtained.

Not every GKS implementation has to support the full set of functions. Nine levels aredefined to meet the different requirements of graphics systems. Each GKSimplementation precisely provides the functions of one level. The levels are upwardcompatible. We present all the functions of level O-a

GKS defines only a language-independent nucleus of a graphics system. For integrationinto a language, GKS is embedded in a language-dependent layer containing thelanguage conventions (for example, parameter, and name assignment).

ApplicationProgram

ApplicationOriented Layer

LanguageDependent Layer

Graphical Kemel System

OPERATING SYSTEM

Other Resources Graphical Resources

Figure 3-1. Layer model of GKS

The layer model represented in Figure 3-1 illustrates the role of GKS in a graphicalsystem. Each layer may call the functions of the adjoining lower layers. In general, theapplication program uses the application oriented layer, the language dependent layerother application dependent layers, and operating system resources. All workstationcapabilities that can be addressed by GKS functions are used only via GKS.


3-2 47 A2 40UL Rev01

3.2 CONCEPTS

The graphical output that is generated by GKS is built up from two groups of basicelements called output primitives and primitive attributes. The output primitives areabstractions of basic actions a device can perform, such as drawing lines and printingcharacter strings. The attributes control the aspects of the output primitives on a device,such as linestyle, colour and character height. Non geometric aspects, such as colour,but not character height, can be controlled for each workstation individually, to makebest use of its capabilities.

A workstation of GKS represents a unit consisting of zero or one display surfaces andzero or more input devices, such as keyboard, tablet and lightpen. The workstationpresents these devices to the application program as a configuration of abstract devicesthereby shielding the hardware peculiarities.

The geometrical information (coordinates) contained in output primitives and attributescan be subjected to transformations. These transformations perform mappings betweenthree coordinate systems, namely:

• World Coordinates (WC), used by the application programmer

• Normalized Device Coordinates (NDC), used to define a uniform coordinate systemfor all workstations

• Device Coordinates (DC), one coordinate system per workstation, representing itsdisplay space coordinates.

Output primitives and attributes are mapped from WC to NDC by normalizationtransformations and from NDC to DC by workstation transformations.

The attribute which controls the appearance of parts of the picture on the display surfaceare organized in a uniform manner. Two groups of attributes apply to the appearance ofeach output primitive: primitive attributes and workstation attributes. Primitive attributesare specified modally and are bound to a primitive when it is created. The primitiveattributes include all geometrical aspects of primitives, such as character height for textand pattern size for fill area. In addition, the non-geometrical aspects of primitives arecontrolled by the primitive attributes in one of two ways. Either a single attribute is usedto specify all the non-geometric aspects of the primitive by an index which points to aworkstation dependent representation (set of values), or one attribute is used to specifyeach 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 asindividual specification.

Workstation attributes incluse the actual representations on a workstation pointed to byindices used in bundled specification of non-geometric aspects. For example, therepresentations (or bundles) for polyline each contain values of linetype, linewidth scalefactor and colour index.

The Graphical Kernel System

47 A2 40UL Rev01 3-3

At run time, GKS can be in one of four different operating states. Associated with eachstate are the set of GKS functions allowed in this state, and a set of state variables. Theoperating state concept and the state variables allow for proper specification ofinitialization (for example at OPEN WORKSTATION) and the effect of various functions,especially with respect to maintaining of device independence. One special set offunctions called inquiry functions is allowed in all states. They give read-only access tothe state list. In this way useful information can be provided when errors occur. Otherinquiry functions allow read-only access to the workstation descriptions, thus permittingthe application program to adapt to particular workstation capabilities. Inquiry functionsnever cause errors. Instead, they return information specifying whether a valid inquirywas made.

GKS provides an interface to a system for filing graphical information for the purpose ofexternal long term storage and exchange. The interface consists of a GKS Metafileoutput workstation, which writes to a so-called graphics metafile (which is sequential)and a GKS Metafile input workstation, which reads from the metafile. In addition to thenormal functions for output to workstations, a GKS Metafile output workstation mayaccept items containing non-graphical information. Input from a metafile is controlled byread and interpret functions which have the same effect as invoking the correspondingfunctions directly from the application program.

At level O-a, metafile workstations are not mandatory; metafile functions returnappropriate error messages.


3-4 47 A2 40UL Rev01

3.3 GRAPHICAL OUTPUT

3.3.1 Output Primitives

The graphical information that is generated by GKS and routed to all active workstationsis built up of basic items called output primitives. GKS provides six output primitives:

POLYLINE to generate a set of connected lines defined by a point sequence.

POLYMARKER to generate symbols of one type centred at given positions.

TEXT to generate a character string at a given position.

FILL AREA to generate a polygonal area which may be either hollow or filledwith a uniform colour, a pattern, or a hatch style.

CELL ARRAY to generate an array of pixels with individual colours.

GENERALIZEDDRAWINGPRIMITIVE

to address special geometrical capabilities of a workstation. Theobjects are characterized by an identifier, a set of points andadditional data. GKS applies all transformations to the points butleaves the interpretation to the workstation. A list of the availableGDPS is given in 3.3.2

3.3.2 Generalized Drawing Primitive

Our implementation of GKS provides seven GDPs:

Box to generate the current clipping rectangle.

Axis to generate graduated axes in the current clipping rectangle,with steps on each axis given by the parameter (if this is 0,the step is calculated according to the WC coordinates).

Autoscale with a list of points given by the parameter, GKS computesthe window of the given normalization transformation. Thiswindow can be centered or not at (0,0), depending on a flaggiven by the parameter.

Circle to generate a circle defined by a center and a point.Arc to generate an arc defined by three points (i.e. abeginning point, an intermediate point and an end point).

Pie to generate a polygonal area composed of an arc defined bythree points (i.e. a beginning point, an intermediate pointand an end point) and two radii.


47 A2 40UL Rev01 3-5

Chord to generate a polygonal area composed of an arc defined bythree points (i.e a beginning point, an intermediate point andan end point) and a chord.

3.3.3 Output Primitive Attributes

Each output primitive potentially has two types of attributes (geometric and non-geometric). These attribute types determine the exact appearance of the outputprimitive. The values of these attributes are set modally and are recorded in the GKSstate list. A separate GKS function is provided for each primitive attribute (except theASF _ see below), to allow the application program to specify the value of an attributewithout unnecessarily specifying the values of other attributes.

During creation of an output primitive (that is, when one of the GKS output primitivefunctions is invoked) these values are bound to the primitive and cannot be changedafterwards.

Attributes of the first type control the geometric aspects of primitives: these are aspectswhich affect the shape or size of a primitive (for example CHARACTER HEIGHT forTEXT). Hence, they are sometimes referred to as geometric attributes. Attributes of thistype are workstation independent and, where appropriate, are expressed in worldcoordinates (for example, CHARACTER HEIGHT is expressed in world coordinates butTEXT PATH takes one of a set of enumerated values). They are defined separately foreach primitive and a primitive may have zero, one or many geometric attributes.

Current values of (workstation independent) geometric attributes, which are expressed inworld coordinates, are stored in world coordinates. When they are bound to theirrespective primitives, the values are subject to the same transformations as thegeometric data contained in the definition of the primitive. Hence, current values areunaffected by changes in the normalization transformation and the workstationtransformation.

Attributes of the second type control the non-geometric aspects of primitives: these areaspects which do not affect the shape or size of a primitive but merely affect itsappearance (for example, linetype for POLYLINE, or colour index for all primitives exceptCELL ARRAY). The non-geometric aspects of a primitive may be specified in one of twoways, namely via a bundle or individually.

For specification of aspects via a bundle, there is one attribute per primitive called the<primitive> INDEX. This attribute is an index into a bundle table, each entry of whichcontains all the non-geometric aspects of the primitive. There is a separate bundle tablefor each primitive with the exception of GENERALIZED DRAWING PRIMITIVE andCELL ARRAY (see below). The non-geometric aspects are workstation dependent in thismethod of specification and each workstation has its own set of bundle tables. Thevalues in a particular bundle (or entry in the bundle table) may be different for differentworkstations.

For individual specification of aspects, there is a separate attribute for each non-geometric aspect. As with the attributes controlling the geometric aspects, theseattributes are workstation independant. Since each non-geometric aspect only occurs inone primitive bundle type, each of these attributes applies to only one primitive type.


3-6 47 A2 40UL Rev01

For a given non-geometric aspect, the values that can be assigned to the appropriatebundle component are the same as the values that can be assigned to thecorresponding attribute for individual specification. Since the bundles are set separatelyfor each workstation, the values of their components are restricted to the valid values forthat workstation. In the case of an individually specified attribute, such restrictions arenot imposed. Default actions for the display of a primitive are defined to occur if it iscreated with a value of an individually specified attribute that is invalid on a particularworkstation.

As indicated above, GENERALIZED DRAWING PRIMITIVE (GDP) and CELL ARRAYdo not have associated bundle tables nor corresponding individually specified attributes.The GDP may use the most appropriate bundle tables or sets of individually specifiedattributes for each GDP function. For example, if one GDP function is essentially a FILLAREA, then the fill area bundle table or the set of individually specified fill area attributeswould be used. CELL ARRAY contains colour index information as part of its definitionbut has no other non-geometric aspects and so does not use a bundle table nor does ithave a set of individually specified attributes.

The method of specification of the non-geometric aspects of a primitive may be chosenseparately for each aspect. A further group of attributes, called ASPECT SOURCEFLAGS (ASFs), take the values INDIVIDUAL and BUNDLED to specify the choice.There is one ASF for each non-geometric aspect of each primitive. The initial values ofall the ASFs are the same: BUNDLED. If the initial values are not altered the system willoperate as if individual specification of non-geometric aspects were not a systemfeature.

The flags may be set at any time when GKS is open by the function SET ASPECTSOURCE FLAGS. This enables some non-geometric aspects of a primitive to bespecified individually and others via a bundle.

When a primitive is displayed, the values of the non-geometric aspects with which it isdisplayed are determined as follows:

• If the ASF for an aspect is INDIVIDUAL, the value used on all workstations is thevalue of the corresponding individually specified attribute of that primitive.

• If the ASF for an aspect is BUNDLED, the value used on a workstation is obtained viathe bundle table for that primitive on the workstation: The corresponding component ofthe bundle, pointed to by the bundle index, is used.

If colour is a non-geometric aspect of a primitive, then it is specified as an index into aseparate colour tables. There is only one colour table per workstation into which all thecolour indices point. Similarly, other entries in a bundle, or corresponding individuallyspecified attributes, may be indices either into another workstation table or into a fixedlist (for example, linetypes for polyline).

The attributes which apply to each output primitive (attributes controlling non-geometricaspects and geometric attributes) are:

a) POLYLINE: POLYLINE INDEXLINETYPELINEWIDTH SCALE FACTORPOLYLINE COLOUR INDEXLINETYPE ASFLINEWIDTH SCALE FACTOR ASFPOLYLINE COLOUR INDEX ASF


47 A2 40UL Rev01 3-7

b) POLYMARKER: POLYMARKER INDEXMARKER TYPEMARKER SIZE SCALE FACTORPOLYMARKER COLOUR INDEXMARKER TYPE ASFMARKER SIZE FACTOR ASFPOLYMARKER COLOUR INDEX ASF

c) TEXT: TEXT INDEXTEXT FONT AND PRECISIONCHARACTER EXPANSION FACTORCHARACTER SPACINGTEXT COLOUR INDEXTEXT FONT AND PRECISION ASFCHARACTER EXPANSION FACTOR ASFCHARACTER SPACING ASFTEXT COLOUR INDEX ASFCHARACTER HEIGHTCHARACTER UP VECTORTEXT PATHTEXT ALIGNMENT

d) FILL AREA: FILL AREA INDEXFILL AREA INTERIOR STYLEFILL AREA STYLE INDEXFILL AREA COLOUR INDEXFILL AREA INTERIOR STYLE ASFFILL AREA STYLE INDEX ASFFILL AREA COLOUR INDEX ASFPATTERN SIZEPATTERN REFERENCE POINT

e) CELL ARRAY: NONE

f) GENERALIZEDDRAWINGPRIMITIVE

Zero or more of the above sets (a) to (e).

The attributes for each primitive are described in 3.3.4. to 3.3.9.

Some standard definitions for table entries are contained in the workstation descriptiontable and are used as initial values. The application program may select a standarddefinition or may define the values of a specific entry explicitly. Only the most commonlyused (or anticipated) combinations of values need be predefined for each output typeworkstation. For the colour table, other combinations of values can be specified by theSET COLOUR REPRESENTATION function. The tables, which are on every workstationof category OUTPUT, OUTIN or MO (i.e. as workstation attributes), are as follows:

• Polyline bundle table• Polymarker bundle table• Text bundle table• Fill area bundle table• Colour table.


3-8 47 A2 40UL Rev01

3.3.4 Polyline Attributes

Polyline has no geometric attributes. The representation of polyline on the workstation iscontrolled the POLYLINE INDEX, or the set of individually specified polyline attributes(LINETYPE, LINEWIDTH SCALE FACTOR, and POLYLINE COLOUR INDEX) or somecombination of the two, depending upon the values of the ASFs for linetype, linewidthscale factor and polyline colour index. The POLYLINE INDEX is a pointer into thepolyline bundle table, each entry of which contains values for linetype, linewidth scalefactor and polyline colour index.

Linetypes 1 to 4 are solid, dashed, dotted and dashed-dotted. Every workstation ofcategory OUTPUT or OUTIN realizes linetypes 1 to 4 with recognizable styles. Thelinetype specifies a sequence of line segments and gaps which are repeated to draw apolyline. This sequence is continued at the start of the polyline, at the start of a clippedpiece of a polyline, and at each vertex of a polyline.

The linewidth is calculated as a nominal linewidth multiplied by the linewidth scale factor.This value is mapped by the workstation to the nearest available linewidth.

On TEKTRONIX 4105, eight different line styles are supported:

1 --------------------- 5 ---...---...---...---

2 - - - - - - - - - - - 6 -- - -- - -- - -- ---

3 ..................... 7 -- -- -- -- -- -- --

4 -.-.-.-.-.-.-.-.-.-.- 8 --- --- --- --- --- ---

and only one linewidth.

On ANDERSON JACOBSON 832 and 833, five different line styles are supported:

1 --------------------- 4 -- - -- - -- - -- - --

2 -- -- -- -- -- -- -- 5 --- --- --- --- --- ---

3 .....................

and only one linewidth.

3.3.5 Polymarker Attributes

Polymarker has no geometric attributes. The representation of polymarker at theworkstation is controlled by the POLYMARKER INDEX, or the set of individuallyspecified polymarker attributes (MARKER TYPE, MARKER SIZE, SCALE FACTOR andPOLYMARKER COLOUR INDEX) or some combination of the two, depending upon thevalues of the ASFs for marker type, marker size scale factor and polymarker colourindex. The POLYMARKER INDEX is a pointer into the polymarker bundle table, eachentry of which contains values for marker type, marker size scale factor and polymarkercolour index.


47 A2 40UL Rev01 3-9

Marker types 1 to 5 are dot, plus sign, asterisk, circle, and diagonal cross, each centredon the positions they are identifying. Every workstation of category OUTPUT or OUTINrealizes marker types 1 to 5 with recognizable shapes at the given positions.

The marker size is calculated as a nominal size multiplied by the marker size scalefactor. This size is mapped by the workstation to the nearest available size. Marker type1 is always displayed as the smallest displayable dot.

The marker is visible if, and only if, the marker position is within the clipping rectangle.

On TEKTRONIX 4105, eleven different marker types are supported:

and only one size.

On ANDERSON JACOBSON 832 ans 833, five different marker types are supported:

and only one size.

3.3.6 Text Attributes

Text has the geometric attributes CHARACTER HEIGHT, CHARACTER UP VECTOR,TEXT PATH and TEXT ALIGNMENT, which are specified and used as described below.

The representation of text at the workstation is controlled by the TEXT INDEX, or the setof individually specified text attributes (TEXT FONT AND PRECISION, CHARACTEREXPANSION FACTOR, CHARACTER SPACING, and TEXT COLOUR INDEX) or somecombination of the two, depending upon the values of the ASFs for text font andprecision character expansion factor, character spacing and text colour index. The TEXTINDEX is a pointer into the text bundle table, each entry of which contains values for textfont and precision, character expansion factor, character spacing and text colour index.


3-10 47 A2 40UL Rev01

Precise control of the appearance of TEXT on a workstation is provided by the followingaspects: CHARACTER HEIGHT, character expansion factor, TEXT PATH,CHARACTER UP VECTOR, character spacing and TEXT ALIGNMENT. However, theuse of these values in displaying text is determined by the setting of the text font andprecision aspect (font and precision are two components of the same aspect). TheCHARACTER HEIGHT specifies the nominal height of a capital letter character. Thecharacter expansion factor specifies the deviation of the width to height ratio of thecharacter from the ratio indicated by the font designer. The CHARACTER UP VECTORgives the up direction of a character. Only the direction, not the lenght, of the vector isrelevant. TEXT PATH has the possible values RIGHT, LEFT, UP and DOWN. Itspecifies the writing direction of the text string. For RIGHT, the text string is written alonga baseline whose direction is a right angle clockwise from the direction of theCHARACTER UP VECTOR. For LEFT, the baseline direction is a right angleanticlockwise from the direction of the CHARACTER UP VECTOR. For UP, thecharacter path coincides with the direction of the CHARACTER UP VECTOR. ForDOWN it is the opposite direction of the CHARACTER UP VECTOR. For the UP andDOWN text path directions, the characters are arranged so that the centers of thecharacter bodies are on a straight line in the direction of the CHARACTER UP VECTOR.

The character spacing value specifies how much additional space is to be insertedbetween two adjacent character bodies. If the value of character spacing is zero, thecharacter bodies are arranged one after the other along the TEXT PATH without anyadditional space between. A positive value of character spacing will insert additionalspace between character bodies. A negative value of character spacing will causeadjacent character bodies to overlap. Character spacing is specified as a fraction of thefont nominal character height.

The effect of the foregoing attributes is to define an (imaginary) enclosing box, the textextent rectangle. The text extent rectangle is rotated in world coordinates, according tothe CHARACTER UP VECTOR. The subsequent description of the bounds andalignment of the text extent rectangle are with respect to a coordinate system rotatedwith the rectangle. For TEXT PATH = LEFT or RIGHT, the height of the rectangle is theheight of the character body of the specified font; the left side of the rectangle is the leftside of the character body of the leftmost character and the right side of the rectangle isthe right side of the character body of the rightmost character. For TEXT PATH = UP orDOWN, the top of the rectangle is the top of the character body of the topmost characterand similarly, the bottom of the rectangle is the bottom of the bottommost character; thewidth is the width of the widest character in the specified font.

The TEXT ALIGNMENT attribute controls the positioning of this text extent rectangle inrelation to the text position. The horizontal component of TEXT ALIGNMENT has fourvalues: LEFT, CENTRE, RIGHT and NORMAL. If the horizontal component is LEFT, theleft side of the text extent rectangle passes through the text position. Similarly, if thevalue is RIGHT, the right side of the text extent rectangle passes through the textposition.


47 A2 40UL Rev01 3-11

If the horizontal component is CENTRE, the text position lies midway between the leftand right sides of the text extent rectangle. Note that if TEXT PATH = UP or DOWN, thestraight line passing through the text position. The vertical component of TEXTALIGNMENT has six values: TOP, CAP, HALF, BASE, BOTTOM and NORMAL. Theseeach correspond to one of the font specific horizontal lines in the definition of a character(see Figure 3-2). A value of TOP causes the top of the text extent rectangle to passthrough the text position. A value of CAP causes the text position to lie on the capline ofthe whole string (TEXT PATH = LEFT or RIGHT) or on the capline of the topmostcharacter in the string (TEXT PATH = UP or DOWN). A value of HALF causes the textposition to lie on the halfline of the whole string (TEXT PATH = LEFT or RIGHT) or on aline halfway between the halflines of the top and bottom characters (TEXT PATH = UPor DOWN). A value of BASE causes the text position to lie on the baseline of the wholestring (TEXT PATH = LEFT or RIGHT) or on the baseline of the bottom character in thestring (TEXT PATH = UP or DOWN). A value of BOTTOM causes the bottom of the textextent rectangle to pass through the text position.

ycentrel ine

body

half l ine

kern

bottoml inerightleft

baseline

capline

X

kern

char

acte

rhe

ight

Figure 3-2. Font description coordinate system

Either component of TEXT ALIGNMENT can take the value NORMAL. For each value ofTEXT PATH the effect of a particular component being NORMAL is equivalent to one ofthe other values of that component. In each case, the equivalent alignement value ischosen to achieve a natural alignment for that TEXT PATH value.

The complete list of equivalent values is:

RIGHT (LEFT, BASE)LEFT (RIGHT, BASE)UP (CENTRE, BASE)DOWN (CENTRE, TOP)


3-12 47 A2 40UL Rev01

The initial values of the geometric text attributes are:

CHARACTER HEIGHT WC 0.01 (i.e. 1% of the height of the default window)CHARACTER UP VECTOR WC 0.1TEXT PATH RIGHTTEXT ALIGNMENT (NORMAL, NORMAL)

Text font and precision together constitute one aspect. The text font value is used toselect a particular font on the workstation. The text precision value is used to select the'closeness' of the text representation at the workstation in relation to that defined by theworkstation independent text attributes and the transformation and clipping currentlyapplicable. The text precision value has the following possible values:

STRING The TEXT character string is generated in the requestedtext font and is positioned by aligning the TEXT outputprimitive at the given text position.

CHARACTER HEIGHT and character expansion factor areevaluated as accurately as the capabilities of theworkstation allow. CHARACTER UP VECTOR, TEXTPATH, TEXT ALIGNMENT and character spacing need notbe used. Clipping is done on a character by character basis.

CHAR The TEXT character string is generated in the requestedtext font. For the representation of each individual character,the aspects CHARACTER HEIGHT, the up direction of theCHARACTER UP VECTOR, and character expansion factorare evaluated as closely as possible, in a workstationdependent way. The spacing used between characterbodies is evaluated exactly; the character body, for thispurpose, is an ideal character body, calculated preciselyfrom the text aspects and the font dimensions. The positionof the resulting text extent rectangle is determined by theTEXT ALIGNMENT and the text position. Clipping isperformed on a character by character basis.

A GKS output level 0 implementation supports text precisions STRING and CHAR.

The font designer specifies the shape of the symbol representing each character in alocal 2D cartesian font coordinate system. Each character in a font coordinate systemhas an associated character body, a font baseline, a font halfline, a capline and acentreline (see Figure 3-2). We use monospaced fonts, so the character bodies of allcharacters have the same size. The character body edges are parallel to the axes of thefont coordinate system. The font baseline, the font halfline and the capline are parallel tothe x-axis of the font coordinate system, and within the vertical extent of the body. Theposition of the font halfline is defined by the font designer for use in aligning text strings.The centreline is parallel to the y-axis and bisects the body. Their exact positions arespecified by the font designer.

The height of a character in the font coordinate system is given by the height from thefont base line to the cap line. The width of a character, which may include space oneither side of the actual character, is given by the width of the character body. It isassumed that the characters lie within their body, except that kerned characters mayexceed the side limits of the character body.

Note that the top limits of the bodies for the font used are identical to the typographicalcapline or ascender line.


47 A2 40UL Rev01 3-13

The effect to be achieved is as follows. Together with the text coding, a height vectorparallel to the CHARACTER UP VECTOR with length equal to CHARACTER HEIGHT,and a width vector perpendicular to the height vector in the direction of the characterbaseline with the same lenght as the CHARACTER HEIGHT vector, are passed downthe viewing pipeline. These vectors are transformed by the normalization transformationand by the workstation transformation. Then the vectors can be used by the workstationcharacter generator.

The height and the direction of the CHARACTER UP VECTOR, on the workstation, aregiven by the transformed height vector. The baseline direction is given by the direction ofthe transformed width vector. The character width is scaled from the font coordinatesystem to device coordinates by the length of the transformed width vector andmultiplied by the character expansion factor. The characters are arranged together in atext extent rectangle, depending on the values of TEXT PATH and character spacing.The text extent rectangle is then positioned according to the value of TEXT ALIGNMENTand the text position, contained in the definition of the TEXT primitive.

Figures 3-3 to 3-5 give examples of the effects of different values of text aspects.


3-14 47 A2 40UL Rev01

OS W g 2I

OS

2g

I

W

Sg

2I

OS W g 2I

OS W g 2I

Exam ples are illustrated w ith ST R O K E precis ion,a character expansion factor o f 1 and a zerocharacter spacing.

character he ight

C H A R A C TE R H E IG H T = 1 , C H A R A C TE R U P V E C TO R = (0,1).T E X T P A T H = R IG H T , T E X T A LIG N M E N T = (N O R M A L, N O R M A L)

C H A R A C T E R H E IG H T = 0,5, C H A R A C TE R U P V E C T O R = (0 ,1)TE X T P A TH = R IG H T, TE X T A LIG N M E N T = (N O R M A L,N O R M A L)

C H A R A C TE R H E IG H T = 1 , C H A R A C TE R U P V E C TO R = (0,1).TE X T P A TH = R IG H T, TE X T A LIG N M E N T = (R IG H T . T O P )

C H A R A C T E R H E IG H T = 1C H A R A C T E R U P V E C T O R = (0 ,1)TE X T P A TH = D O W NTE X T A LIG N M E N T = (N O R M A L,N O R M A L)

C H A R A C TE R H E IG H T = 1C H A R A C TE R U P V E C TO R = (-1 ,0)T E X T P A T H = R IG H TT E X T A LIG N M E N T = (N O R M A L, N O R M A L)

tex t pos itionbaseline or centre linetex t ex tent rec tang le(indicated for P A TH = D O W N )capline = topline in these exam ples

Note:

Figure 3-3. Effects of changes in geometric text aspects(change aspects are underlined)


47 A2 40UL Rev01 3-15

OS W g 2I

OS W g 2I

Exam ples are illus trated w ith defau lt values o f thegeom etric text attributes and w ith STR O K E prec is ion.

C H A R A C TE R E X P A N S IO N F A C TO R = 1. C H A R A C TE R S P A C IN G = 0

C H A R A C TE R E X P A N S IO N FA C TO R = 1. C H AR A C T E R S P A C IN G = 0,3

Figure 3-4. Effects of changes in non-geometric text aspects(changed aspects are underlined)

OS

2g

I

W

Sg

2I

O SWg2 I

C H A R A C TE R E X P A N S IO N FA C TO R = 1C H A R A C TE R S P A C IN G = 0H A R A C TE R H E IG H T = 1C H A R A C TE R U P V E C TO R = (-1 ,0)T E X T P A TH = LE FTT E X T A LIG N M E N T = (C E N TR E , TO P )

Note:half l ines of al l charactersare shown in th is example

C H A R A C TE R E X P A N S IO N F A C TO R = 1C H A R A C TE R S P A C IN G = -0 ,3C H A R A C TE R H E IG H T = 1C H A R A C TE R U P V E C TO R = (0,1)T E X T P A T H = LE FTT E X T A LIG N M E N T = (N O R M A L, N O R M A L)

C H A R A C T E R E X P A N S IO N FA C TO R = 1C H A R A C T E R S P A C IN G = 0C H A R A C T E R H E IG H T = 1C H A R A C T E R U P V E C TO R = (0, 1)TE X T P A TH = D O W NTE X T A LIG N M E N T = (LE FT, H A LF )

Figure 3-5. Effects of combined changes in text aspects(changed aspects are underlined)


3-16 47 A2 40UL Rev01

On TEKTRONIX 4105, we support only one font with precision STRING and CHAR. In aspace 480 x 360, the font description is:

top l ine, cap l ine

half l ine

base l ine

bottom l inele ft centreline

8

4

A

AV

V

righ t

We support only one character expansion factor (1). Character height can take threevalues (8, 16, 24 pixels). Character up vector has four values:

On ANDERSON JACOBSON 832 and 833, we support only one font with precisionSTRING and CHAR. In a space 33.3 x 27.9 cm the font description is:

A

V

< >0,21 cm

0, 32 cm

top l ine, cap l ine

half l ine

base l ine, bottom l ine

left centre right line

We support only one character expansion factor (1), one character height (0.32 cm) andone character up vector (0,1).


47 A2 40UL Rev01 3-17

3.3.7 Fill Area Attributes

The representation of fill area at the workstation is controlled by the FILL AREA INDEX,or the set of individually specified fill area attributes (FILL AREA INTERIOR STYLE, FILLAREA STYLE INDEX, and FILL AREA COLOUR INDEX) or some combination of thetwo, depending upon the values of the AFSs for fill area interior style, fill area style index,and fill area colour index. The FILL AREA INDEX is a pointer into the fill area bundletable, each entry of which contains values for the fill area interior style, fill area styleindex and fill area colour index.

The fill area interior style is used to determine in what style the area should be filled. Ithas the following values:

HOLLOW No filling, but draw the bounding polyline, using the fill areacolour index currently selected (either via the fill area bundleor individually, depending upon the corresponding ASF). Weuse linetype number one.

SOLID Fill the interior of the polygon using the fill area colour indexcurrently selected (either via the fill area bundle orindividually, depending upon the corresponding ASF).

PATTERN Fill the interior of the polygon using the fill area style indexcurrently selected (either via the fill area bundle orindividually, depending upon the corresponding ASF) as anindex into the pattern table; in this context the fill area styleindex is sometimes referred to as the pattern index.

HATCH Fill the interior of the polygon using the fill area style indexcurrently selected (either via the fill area bundle orindividually, depending upon the corresponding ASFs). Thefill area style index is used as a pointer into the list of hatchstyles, in which case it is sometimes referred to as the hatchindex.

For interior style PATTERN, the pattern is defined by the pattern representation. A grid ofcells is defined. The colour is specified individually for each cell by a colour index, whichis a pointer into the colour table.

For interior style HATCH, the hatch index selects among workstation dependent hatchpatterns. Hatching is not affected by transformations.

On TEKTRONIX 4105, we support the four interior styles. We support 16 different hatchindices (index 1 to 16) and 124 different pattern indices (index 51 to 174). These indicesrefer to the predefined patterns of the terminal for filling panels, so the pattern size andpattern reference point attributes cannot be used.

On ANDERSON JACOBSON 832 and 833, only interior styles hollow and hatch aresupported. For interior style hatch, we draw also the boundaries. We support 16 differenthatch indices which are presented in Figure 3-6.


3-18 47 A2 40UL Rev01

index 1

index 5

index 11

index 15

index 2

index 6

index 3

index 7

index 4

index 8

index 12

index 16

index 13

index 17

index 14

index 18

Figure 3-6. Hatch index for ANDERSON JACOBSON 832 and 833

3.3.8 Cell Array Attributes

Cell array has no attributes. However, an array of colour indices, which are pointers intothe colour table, is part of the definition of a cell array.


47 A2 40UL Rev01 3-19

3.3.9 Generalized Drawing Primitive Attributes

Generalized Drawing Primitive (GDP) has no explicit geometric attributes. Suchinformation may be specified in the GDP data record. The representation of the GDP atthe workstation is controlled by zero or more of the sets of polyline, polymarker, text andfill area attributes. Whether bundle indices or associated individually specified attributesare used depends upon the values of the appropriate ASFs. The sets of attributes mostappropriate for the specified GDP function are selected for the GDP as part of thedefinition of the GDP and are recorded in the workstation description table.

For each generalized drawing primitive, we use:

Box: Polyline set of attributesAxis: Polyline set of attributesAutoscale: NoneCircle: Fill area set of attributesArc: Polyline set of attributesPie: Fill area set of attributesChord: Fill area set of attributes

Note that on ANDERSON JACOBSON 832 and 833, the GDP circle, arc, pie and chorddo not use any set of attributes. The figure is always hollow and drawn with linestylenumber one.

3.3.10 Colour

In GKS, colour is specified in a number of different situations. It may be an aspect of aprimitive, in which case it is specified either in the bundle for that primitive or by theindividual colour attribute for that primitive. It may be part of a pattern for FILL AREA, inwhich case an array of colours is specified, or it may be part of a primitive itself, namelyCELL ARRAY, when an array of colours is also specified. In each case, the colour isspecified as an index into a colour table on the workstation. On each workstation, thereis one colour table into which all the colour indices point.

The size of the colour table is workstation dependent but entries 0 and 1 always exist.Entry 0 corresponds to the background colour. The background colour is the colour ofthe display surface after it has been cleared. Entry 1 is the default foreground colour andentries higher than 1 correspond to alternative foreground colours. Entries in the tablemay be set by the function SET COLOUR REPRESENTATION which specifies thecolour as a combinaton of red, green, and blue intensities. The specified colour ismapped to the nearest available by the workstations.

Some workstations are not capable of displaying colours (as in the case of ANDERSONJACOBSON 832 and 833); these are referred to as monochrome workstations. Whethera workstation is capable of colour is recorded in the *``Colour available''* entry in theworkstation description table.

On TEKTRONIX 4105, there are 8 entries in the colour table. Colour can be chosen from64 different colours.


3-20 47 A2 40UL Rev01

3.3.11 Workstation Dependent Bundle Table

The non geometrical aspects of primitives can be controlled via the bundle table. In thisway, a single attribute is used to specify all the non geometric aspect of the primitive byan index which points to a workstation dependent representation. We detail below foreach type of terminal the workstation dependent bundle tables.

3.3.11.1 ANDERSON JACOBSON Bundle Tables

Polyline Bundle TableIndex Linestyle Linewidth Line colour

1 1 1 12 1 1 23 1 1 34 2 1 15 2 1 26 2 1 37 3 1 18 3 1 29 3 1 310 4 1 111 4 1 212 4 1 313 5 1 114 5 1 215 5 1 3

Note that the different line colour corresponds to a simulation of colour. For line colour 2,line is drawn with symbol asterisk (and not dot) and for line colour 3, line is drawn withsymbol plus (and not dot).

Polymarker Bundle TableIndex Marker type Marker size sale factor Marker colour

1 1 1 12 2 1 13 3 1 14 4 1 15 5 1 1

Text Bundle TableIndex Text font and

precisionCharacter

expansion factorCharacterspacing

Text colour

1 1, string 1 0 12 1, char 1 0 13 1, char 1 0.3125 14 1, char 1 -0.3125 1


47 A2 40UL Rev01 3-21

Fill Area Bundle TableIndex Fill area interior style Fill area style index Fill area colour

1 0 (hollow) 0 12 3 (hatch) 1 13 3 2 14 3 3 15 3 4 16 3 5 17 3 6 18 3 7 19 3 8 110 3 11 111 3 12 112 3 13 113 3 14 114 3 15 115 3 16 116 3 17 117 3 18 1


3-22 47 A2 40UL Rev01

3.3.11.2 TEKTRONIX 4105 Bundle Tables

Polyline Bundle TableIndex Line type Linewidth scale factor Line colour

1 1 1 12 2 1 13 3 1 14 4 1 15 1 1 26 2 1 27 3 1 28 4 1 29 1 1 310 2 1 311 3 1 312 4 1 313 1 1 414 2 1 415 3 1 416 4 1 417 1 1 518 2 1 519 3 1 520 4 1 521 1 1 622 2 1 623 3 1 624 4 1 625 1 1 726 2 1 727 3 1 728 4 1 729 1 1 030 2 1 031 3 1 032 4 1 0


47 A2 40UL Rev01 3-23


1 1 1 12 2 1 13 3 1 14 4 1 15 5 1 16 1 1 27 2 1 28 3 1 29 4 1 210 5 1 211 1 1 312 2 1 313 3 1 314 4 1 315 5 1 316 1 1 417 2 1 418 3 1 419 4 1 420 5 1 421 1 1 722 2 1 723 3 1 724 4 1 725 5 1 726 1 1 027 2 1 028 3 1 029 4 1 030 5 1 0


3-24 47 A2 40UL Rev01

Text Bundle TableIndex Text font and

precisionCharacter

expansion factorCharacterspacing

Text colour

1 1, string 1 0 12 1, string 1 0 23 1, string 1 0 34 1, string 1 0 45 1, string 1 0 56 1, string 1 0 67 1, string 1 0 78 1, string 1 0 09 1, char 1 0 110 1, char 1 0 211 1, char 1 0 312 1, char 1 0 413 1, char 1 0 514 1, char 1 0 615 1, char 1 0 716 1, char 1 0 017 1, char 1 0.3125 118 1, char 1 0.3125 219 1, char 3 0.3125 320 1, char 4 0.3125 421 1, char 1 0.3125 522 1, char 1 0.3125 623 1, char 1 0.3125 724 1, char 1 0.3125 025 1, char 1 -0.3125 126 1, char 1 -0.3125 227 1, char 1 -0.3125 328 1, char 1 -0.3125 429 1, char 1 -0.3125 530 1, char 1 -0.3125 631 1, char 1 -0.3125 732 1, char 1 -0.3125 0


47 A2 40UL Rev01 3-25


1 0 (Hlow) 0 02 1(Slid) 1 13 1 1 24 1 1 35 1 1 46 1 1 57 1 1 68 1 1 79 1 1 010 3 (Hatch) 1 011 3 2 012 3 3 013 3 4 014 3 5 015 3 6 016 3 7 017 3 8 018 3 9 019 3 10 020 3 11 021 3 12 022 3 13 023 3 14 024 3 15 025 3 16 0


3-26 47 A2 40UL Rev01

3.4 WORKSTATIONS

3.4.1 Workstation Characteristics

GKS is based on the concept of abstract graphical workstations. These provide thelogical interface through which the application program controls physical devices.

For every type of workstation present in a GKs implementation (except for the specialworkstations), there exists a workstation description table which describes thecapabilities and characteristics of the workstation. The application program can inquirewhich capabilities are available and adapt its behaviour accordingly. If capabilities arerequested that a particular workstation does not provide, a standard error reaction isdefined.

An abstract graphical workstation with maximum capabilities:

• Hs one addressable display surface of fixed resolution.

• Alows only rectangular display spaces (the display space does not consist of anumber of separate parts).

• Permits the specification and use of smaller display spaces than the maximum whileguaranteeing that no display image is generated outside the specified display space.

• Supports several linetypes, text fonts, character sizes, etc, to allow output primitives tobe drawn with different aspects.

In practice, the workstation is not necessarily equipped with all of these capabilities.

Each workstation has a type, and each type falls into one of six categories:

• TPUT (output)• PUT (input)• OUTIN (output and input)• WISS (Workstation Independent Segment Storage)• MO (GKS Metafile Output)• MI (GKS Metafile Input)

A workstation of category OUTPUT has only output capabilities. It can display all outputprimitives, with the possible exception of the GENERALIZED DRAWING PRIMITIVE,which is optional.

A workstation of category INPUT has at least one logical input device, but no outputcapability.


47 A2 40UL Rev01 3-27

A workstation of category OUTIN has the characteristics of both an OUTPUT and INPUTworkstation. In addition, the existence of a workstation in this category in a GKSimplementation gives rise to additional requirements regarding logical input devices.

The last three categories WISS, MO and MI are special GKS facilities that provide ameans for temporarily or permanently storing graphical information. They are treated asworkstations for the purposes of control, but otherwise have quite differentcharacteristics.

Note that all the workstations we support are of category OUTPUT.

3.4.2 Selecting a Workstation

The application program references a workstation by means of a workstation identifier.Connection to a particular workstation is established by the function OPENWORKSTATION, which associates the workstation identifier with a workstation type.The current state of each open workstation is kept in a workstation state list.

Output primitives are sent to the active workstation and no others; an open workstation ismade 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.

To allow portability between different types of workstation, the function INQUIREWORKSTATION CONNECTION AND TYPE permits the user, in the state GKOP, toknow the type of the working workstation.

In a FORTRAN program, this sequence permits the writing of a program independent ofthe type of terminal:

INTEGER IDENT, ERRIND, CONID, TYPECALL GOPKSIDENT = 1CALL GQWKC (IDENT, ERRIND, CONID, TYPE)CALL GOPWK (IDENT, CONID, TYPE)

In a COBOL program, the following sequence has the same effect:

77 IDENT COMP-2 VALUE 1.77 ERRIND COMP-2.77 CONID COMP-2.77 TYPE COMP-2.

CALL ``GOPKSC''*.MOVE 1 TO IDENT.CALL ``GQWKC`` USING IDENT, ERRIND, CONID, TYPE.CALL ``GOPWK`` USING IDENT, CONID, TYPE.


3-28 47 A2 40UL Rev01

3.5 COORDINATE SYSTEMS AND TRANSFORMATIONS

3.5.1 Normalization Transformation

In GKS, the application programmer can compose his graphical picture from separateparts, each of which, conceptually, is defined with its own world coordinate system (WC).The relative positioning of the separate parts is defined by having a single normalizeddevice coordinate space (NDC) onto which all the defined world coordinate systems aremapped. A set of normalization transformations defines the mappings from the worldcoordinate systems onto the single normalized device coordinate space, which can beregarded as a workstation independent abstract viewing surface.

For output, a single normalization transformation is current at any one time and this isused to transform world coordinates specified, for example in output primitives andgeometric attributes, into normalized device coordinates.

A normalization transformation is specified by defining the limits of an area in the worldcoordinate system (window) which is to be mapped onto a specified area of thenormalized device coordinate space (viewport). Window and viewport limits specifyrectangles parallel to the coordinate axes in WC and NDC. The rectangles include theirboundaries. The normalization transformation performs a mapping from WC onto NDCthat includes translation and differential scaling with positive scale factors for the twoaxes.

Although NDC space conceptually extends to infinity, the part of NDC space in which theviewport must be located and that can be viewed at a workstation is the closed range[0,1]x[0,1].

Each normalization transformation is identified by a transformation number which is aninteger between 0 and 31. The normalization transformation with transformation number0 is the unity transformation which maps [0,1]x[0,1] in world coordinates to [0,1]x[0,1] innormalized device coordinates. It cannot be changed.

Initially, all other normalization transformations are set to a default transformation whichis the same as transformation number 0. Different transformations can be specified atany time when GKS is open.

A normalization transformation may be selected by SELECT NORMALIZATIONTRANSFORMATION, and it will be used for all output until another is selected. Bydefault, normalization transformation 0 is selected.


47 A2 40UL Rev01 3-29

3.5.2 Clipping

The viewport of a particular normalization transformation can be used to define a clippingrectangle, as well as, with the window, specifying the normalization transformation.Clipping to the viewport boundary can either be enabled or disabled. There is a singleglobal switch which defines whether or not the current viewport is to be used as theclipping rectangle.

Clipping does not take place when the normalization transformation is performed bu isdelayed until the output primitives are to be displayed on the display surface of aworkstation.

3.5.3 Workstation Transformations

The normalized device coordinate space can be regarded as a workstation idenpendentabstract viewing surface. Each open workstation can select independently some part ofthe NDC space in the range [0,1]x[0,1] to be displayed somewhere on the workstationdisplay surface. A particular workstation transformation is a mapping from NDC spaceonto the device coordinates (DC) for that workstation. The limits of the devicecoordinates are available from the workstation description table.

The workstation transformation is a uniform mapping from NDC onto DC and thusperforms translation and equal scaling with a positive scale factor for the two axes. Thuspicture composition can be achieved using the normalization transformations whereasthe workstation transformation allows different aspects of the composed picture to beviewed on different workstations. For example, a drawing could be output to a plotter atthe correct scale and simultaneously some part of the drawing could be displayed on thefull display surface of an interactive terminal.

A workstation transformation is specified by defining the limits of an area in thenormalized device coordinate system within the range [0,1]x[0,1] (workstation window)which is to be mapped onto a specified area of the device coordinate space (workstationviewport). Workstation window and workstation viewport limits specify rectangles parallelto the coordinate axes in NDC and DC. The rectangles include their boundaries. Toensure that no output outside the workstation window is displayed, GKS clips at theworkstation window boundaries, and this clipping cannot be disabled. As the workstationwindow is defined somewhere in the NDC range [0,1]x[0,1], this ensures that the onlypart of NDC space that can be viewed on any workstation lies in the range [0,1]x[0,1].

If the workstation window and workstation viewport have different aspect ratios, thescaling specified would be different on each axis if the workstation window was mappedonto the workstation viewport in its entirety.

To ensure equal scaling on each axis, the workstation transformation maps theworkstation window onto the largest rectangle that can fit within the workstation viewportsuch that:

• aspect ratio is preserved• the lower left-hand corner of the workstation window is mapped to the lower left-hand

corner of the workstation viewport.

Thus, space is left unused at the top or right side of the workstation viewport if theaspect ratios of the workstation window and workstation viewport are different.


3-30 47 A2 40UL Rev01

All workstation transformations are set by default to map NDC space [0,1]x[0,1] onto themaximum workstation display surface. If the display surface is not square, the samerules as above apply to achieve equal scaling on each axis.

workstation transformations can be changed by SET WORKSTATION WINDOW or SETWORKSTATION VIEWPORT.

On ANDERSON JACOBSON 832 and 833, device coordinates are expressed incentimeters. The dimensions of the maximum workstation display surface are:

[0,33.3] x [0,27.9]

On TEKTRONIX 4105, device coordinates are expressed in pixel. The dimensions of themaximum workstation display surface are:

[0,4095] x [0,3132]

The origin is at the lower left-hand corner of the display surface.


47 A2 40UL Rev01 3-31

3.6 STATES OF GKS AND INQUIRY FUNCTIONS

3.6.1 Description Of States

GKS exists in one of four different operating states (see Figure 3-7):

GKCL = GKS closedGKOP = GKS openWSOP = One Workstation openWSAC = One Workstation active.

The operating state value is contained in a global static variable that is initialized, beforethe first invocation of GKS, to the value GKCL. The operating states differ in so far asindividual calls to GKS are allowed only in certain operating states.

The overall state of GKS is defined by a set of state variables having specific values.These state variables are characterized by the fact that they allow a complete descriptionof the effects of the functions. The total set of GKS state variables contains the followingsubsets:

• operating state• GKS state list• workstation state list.

Certain functions cause these state subsets to be allocated, made available andcancelled. When these state subsets are allocated they are initialized with default values.When initializing a workstation state list, some of the default values are taken from aworkstation description table which contains an entry for each workstation typesupported by the GKS implementation. The variables of the state subsets are modifiedand inquired by invocations of GKS functions.

When an error condition is detected during execution of a GKS function, GKS calls theERROR HANDLING procedure. During execution of the ERROR HANDLING procedure,GKS is in an error state. In this error state, GKS allows only inquiry functions, theERROR LOGGING procedure and the EMERGENCY CLOSE GKS procedure to beexecuted and no modifications to any of the state lists except the error state list.

3.6.2 Inquiry Function

Inquiry functions return values directly from, or derived from, the various state lists andworkstation description tables. The data types of the values and the default values of theentries are summarized in Section 6.


3-32 47 A2 40UL Rev01

The inquiry functions of GKS are designed in such a way that they do not cause anyerrors to be generated. Inquiry functions for values that may be logically unavailable havean output parameter, `èrror indicator``, that determines whether or not the other returnedvalues are valide. The availability parameter is of type integer and, in the event of theother values not being available, returns an error number, which identifies the appropriateGKS error condition. The same error numbers are used as for non-inquiry functions andthus the standard list of error messages should be consulted. If the values are available,zero is returned in the error indicator parameter.

For all the values except zero, the returned values are implemention dependent. Thedescription of each inquiry function lists the error indicator values that the function canreturn.

V

A

V

A

V

A

C loseG K S

C losew orks ta tion

A ttribu te se tting

D eactiva tew orks ta tion

Primit ive generat ionattr ibute sett ing

G K Sclosed

G K Sopen

At least oneworkstat ion

open

At least oneworkstat ion

act ive

OpenG K S

Openworkstat ion

Figure 3-7. Possible Transitions between Operating states


47 A2 40UL Rev01 3-33

3.7 ERROR HANDLING

For each GKS function, a finite number of error situations is specified, any of which willcause the ERROR HANDLING procedure to be called. Every GKS implementationsupports this error checking. The ERROR HANDLING procedure provides an interfacebetween GKS and the application program. The ERROR HANDLING procedure, ifprovided by the application program, may interpret the information about the error andmay store data in a data area for subsequent interpretation by the application programafter return from the GKS function that caused the error.

The EMERGENCY CLOSE GKS procedure permits the direct closing of GKS in anyoperating state.

The application program may either provide its own ERROR HANDLING procedure ormay use that provided as part of GKS. Any ERROR HANDLING procedure accepts thefollowing information from GKS:

• the identification of the error condition,• the identification of the GKS function which called the ERROR HANDLING procedure,• the error file.

The ERROR HANDLING procedure provided by GKS just calls the ERROR LOGGINGprocedure, using the same set of parameters. The latter performs the following actions:

• prints an error message and GKS function identification on the error file,• Returns to the calling procedure.

This two-stage calling of the error procedures allows the application program to supply itsown ERROR HANDLING procedure, while still having access to services provided by theERROR LOGGING procedure, as shown in the following example of an applicationprogram supplied ERROR HANDLING procedure:

PROCEDURE GERHND (error number, identification of GKS function, error file),Interpret GKS function and error identification in order to select the following cases:

• CASE ``special treatment``,Interpret error parameters as passed from GKS,Store information for application program in application supplied data area,Return to calling GKS procedure.

• CASE ``standard treatment``.Call ERROR LOGGING procedure with all the above parameters.Return to calling GKS procedure.

• END.


3-34 47 A2 40UL Rev01

IMPORTANT

When the application program provides its own ERROR HANDLING,it must call it GERHND and must add in the linker commandlanguage the statement:

INCLUDE = GERHND

If error logging is called without the parameter error file, errorstatements are displayed on the terminal.

All GKS procedures perform the following actions after detecting an error condition:

• set error state to ON,• call ERROR HANDLING procedure with appropriate parameters,• set error state to OFF,• perform built-in error reaction (normally a function causing an error has no effect, but

to accomplish this in some cases requires clean-up operations).

All GKS procedures check on entry (in the following order):

• that GKS is in the correct state,• that the values of input parameters are valid.

At least the first error detected is reported.


47 A2 40UL Rev01 3-35

>

>

>

V

V

V

A

Fortranprogram

G K Sfunct ions

E R R O R ?

GERHND ex is ts ?

G E R L O G

G E R H N D

yes

no

noyes

Application program GKS function

Figure 3-8. TREATMENT of ERRORS


3-36 47 A2 40UL Rev01

47 A2 40UL Rev01 4-1

4. Language Bindings

4.1 INTRODUCTION

For integration into a programming language, GKS is embedded in a languagedependent layer obeying the particular conventions of that language. Some rules areidentical for all presented languages, for example the representation of enumerationtypes and the GKS function identification. We present these at the beginning and thenthe particularities of the FORTRAN interface and the COBOL interface.

4.2 ENUMERATION TYPES

All the enumeration types of GKS are mapped to integers. The correspondance betweenGKS scalars and these integers are shown in Table 4-1. The following section containsthe method of mapping GKS enumeration types to integers.

Table 4-1. Enumeration type

* Aspect source flag bundled : 0 Individual : 1

* Clear Control flag Conditionally : 0 Always : 1

* Clipping indicator Noclip : 0 Clip : 1

* Colour available Monochrome : 0 Colour : 1

* Deferral mode ASAP : 0 BNIG : 1 BNIL : 2 ASTI : 3

* Device coordinate units Metres : 0 Others : 1

* Display surface empty Notempty : 0 Empty : 1


4-2 47 A2 40UL Rev01

* Fill area interior style Hollow : 0 Solid : 1 Pattern : 2 Hatch : 3

* Implicit regeneration mode Suppressed : 0 Allowed : 1

* Level of GKS L0a : 0 L0b : 1 L0c : 2 L1a : 3 L1b : 4 L1c : 5 L2a : 6 L2b : 7 L2c : 8

* New frame action necessary at update No : 0 Yes : 1

* Operating state value GKCL : 0 GKOP : 1 WSOP : 2 WSAC : 3

* Presence of invalid values Absent : 0 Present : 1

* Regeneration flag Suppress : 0 Perform : 1

* Text alignment horizontal Normal : 0 Left : 1 Center : 2 Right : 3

* Text alignment vertical Normal : 0 Top : 1 Cap : 2 Half : 3 Base : 4 Bottom : 5

* Text path Right : 0 Left : 1 Up : 2 Down : 3

* Text precision String : 0 Char : 1 Stroke : 2

* Type of returned values Set : 0 Realized : 1

* Update state Not pending : 0 Pending : 1

* Vector/Raster/Other types Vector : 0 Raster : 1 Other : 2

* Workstation category Output : 0 Input : 1 Outin : 2 Wiss : 3 MO : 4 MI : 5

* Workstation state Inactive : 0 Active : 1

* List of GDP attributes Polyline : 0 Polymarker : 1 Text : 2 Fill area : 3

* Linetype Solid : 1 Dash : 2 Dot : 3 Dash-Dotted : 4

Language Bindings

47 A2 40UL Rev01 4-3

* Marker type Point : 1 Plus : 2 Asterisk : 3 Zero : 4 Cross : 5

* Workstation type ANDERSON JACOBSON 832 : 1 ANDERSON JACOBSON 833 : 2 TEKTRONIX 4105 : 3

4.3 GKS FUNCTION IDENTIFICATION

For error handling, a function identification is necessary. All the function identifications ofGKS are mapped to integers. The correspondance between FORTRAN or COBOLfunctions and these integers is shown in Table 4-2.

Table 4-2. Function Identification

GOPKS (Fortran) 0 GOPKSC (Cobol) 0 GCLKS 1GOPWK 2 GCLWK 3 GACWK 4GDAWK 5 GCLRWK 6 GUWK 8GESC 11 GPL 12 GPM 13GTX (Fortan) 14 GTXS (Cobol) 14 GFA 15GCA 16 GGDP 17 GSPLI 18GSLN 129 GSLWSC 20 GSPLCI 21GSPMI 22 GSMK 23 GSMKSC 24GSPMCI 25 GSTXI 26 GSTXFP 27GSCHXP 28 GSCHSP 29 GSTXCI 30GSCHH 31 GSCHUP 32 GSTXP 33GSTXAL 34 GSFAI 35 GSTAIS 36GSFASI 37 GSFACI 38 GSPA 39GSPARF 40 GSASF 41 GSCR 48GSWN 49 GSVP 50 GSELNT 52GSCLIP 53 GSWKWN 54 GSWKVP 55GWITM 101 GGTITM 102 GRDITM 103GIITM 104


4-4 47 A2 40UL Rev01

4.4 FORTRAN INTERFACE

4.4.1 Introduction

The FORTRAN interface complies with the proposal of ISOTC97/SC5/WG2 'FORTRANinterface for GKS 7.2' (November 1983). It is a language binding interface for ANSIFORTRAN 77. The function names of the ISO/DIS 7942 GKS are mapped to FORTRANsubroutine names which start with the letter 'G'. The remaining letters after the first oneare chosen by deriving a unique abbreviation of the single words of the name (e.g.ACTIVATE becomes AC).

The functions of GKS are all mapped to FORTRAN subroutines. Generally, the order ofGKS function parameters is not changed; for some subroutines, however, there areadditional parameters which may be inserted in the normal parameter sequence. Thereis a standard error routine which calls an error logging routine named GERLOG. Theuser may replace the standard error routine by his own one, using the name GERHND.Furthermore, these user defined error routines may call the system defined error loggingprocedure GERLOG.

IMPORTANT

The application program must include in its linker commandlanguage the statement:

STACK3 = (INITSIZE = 2048, MAXSIZE = 64K, PAGING = NO)

4.4.2 Representation of Cell Array and Pixel Array

The representation of CELL ARRAY and PIXEL ARRAY allows the user of the routinesrequiring a cell array parameter to pass any portion of the array as an argument. Twoexamples should make this clear.

Certainly the user can pass an entire two-dimensional array. In this case the number ofrows and columns of the cell array are the same as the number of rows and columns ofthe portion passed:

INTEGER DX , DY , CELLS (DIMX, DIMY)CALL GCA (X1, Y1, X2, Y2, DIMX, DIMY, 1, 1, DIMX, DIMY, CELLS)

(1,1) (2,1) (3,1) ... (DIMX,1) (1,2) (2,2) (3,2) ... (DIMX,2) . . . . . . . . . . . . (1,DIMY) (2,DIMY) (3,DIMY) ... (DIMX,DIMY)

Language Bindings

47 A2 40UL Rev01 4-5

To use an arbitrary portion of an array the user passes in addition to the cell array and itsdimensions the indices of the upper left corner of the portion as starting address and thenumber of rows and columns of the portion to be passed. The area inside the asterisksis the cell array being passed.

INTEGER STARTX, STARTY, DX, DY, DIMX, DIMY, CELLS (DIMX, DIMY)DATA STARTX/3/, STARTY/6/, DX/2/, DY/3/CALL GCA (X1, Y1, X2, Y2,* DIMX, DIMY, STARTX, STARTY, DX, DY, CELLS)

(1,1) (2,1) (3,1) (4,1) ... (DIMX,1) (1,2) (2,2) (3,2) (4,2) ... (DIMX,2) . . . . . . . ********************** . (1,6) (2,6) * (3,6) (4,6) * ... (DIMX,6) (1,7) (2,7) * (3,7) (4,7) * ... (DIMX,7) (1,8) (2,8) * (3,8) (4,8) * ... (DIMX,8) . . ********************** . . . . . . (1,DIMY) (2,DIMY) (3,DIMY) (4,DIMY) ... (DIMX,DIMY)


4-6 47 A2 40UL Rev01

4.5 COBOL INTERFACE

4.5.1 Introduction

There is currently no proposed COBOL interface from the international comittee WG2.Our interface is based on the FORTRAN interface. The application may just call theFORTRAN interface functions except for some functions which are detailed below.

The functions of GKS are all mapped to COBOL procedure. Generally, the order of GKSfunction parameters is not changed. For some procedures, however, there are additionalparameters which may be inserted in the normal parameter sequence.

The representation of enumeration types is identical in COBOL programs and inFORTRAN programs.

Some functions have a different entry point in COBOL and FORTRAN.

These functions are:

Open GKS:Text functions:Error routines:

GOPKSCGTXS or GQTXXSGERLOGC

IMPORTANT

The application must add in its COBOL compiler command languagethe statement:

LEVEL = 64

and it must add in its linker command language, the statements:

STACK3 = (INITSIZE = 2048, MAXSIZE = 64 K, PAGING = NO),LINKTYPE = (SCIENT),

Language Bindings

47 A2 40UL Rev01 4-7

4.5.2 Data Formats

The array below indicates the correspondence of data formats between FORTRAN 77and COBOL programs.

COBOL FORTRAN 77Text PIC X (n) Character *n

Integer COMP-2 IntegerReal COMP-9 REAL

Array of 01 A1 Integer A (n,m)integer 02 A2 occurs m

03 A3 occurs n

4.5.3 Open GKS

To open GKS, a COBOL program must call the function "GOPKSC". The effects ofcalling the FORTRAN subroutine GOPKS from a COBOL program are unpredictable.

This function has one parameter, the error file. This file must be declared with SSFformat. If this parameter is not specified, error messages will be written on the terminal.

OPEN GKS GKCL

CALL "GOPKSC" [USING ERRFIL].

Input parameters:

SELECT ERRFIL ASSIGN TO ifn WITH SSF. File error . . .FD ERRFIL.


4-8 47 A2 40UL Rev01

4.5.4 Text Functions

To write a text, a COBOL program must call the function "GQTXS" which has fourparameters.

To inquire the text extent rectangle, a COBOL program must call the function"GQTXXS".

A COBOL program must specify the length of the string of characters:

TEXT WSAC

CALL "GTXS" USING PX, PY, LG, CHARS.

Input parameters:

77 PX COMP-9. Text position in WC77 PY COMP-9.77 LG COMP-2. Length of the text77 CHARS PIC X(n) Character string

INQUIRE TEXT EXTENT WSOP, WSAC

CALL "GQTXXS" USING WKID, PX, PY, LG, STR, ERRIND, CPX, CPY, TXEXPX(1), TXEXPY(1).

Input parameters:

77 WKID COMP-2. Workstation identifier77 PX COMP-9. Text position in WC77 PY COMP-9.77 LG COMP-2. Length of the string77 STR PIC X(n). Character string

Output parameters:

77 ERRIND COMP-2. Error indicator77 CPX COMP-9. Concatenation point in WC77 CPY COMP-9.01 TXEXX. Text extent rectangle 02 TXEXPX COMP-9 OCCURS 4.01 TXEXY. 02 TXEXPY COMP-9 OCCURS 4.

Language Bindings

47 A2 40UL Rev01 4-9

4.5.5 Error Procedures

There is a standard error routine which calls an error logging routine named GERLOGC.The user may replace the standard error routine by his own one, using the nameGERHND, and adding in his linker command the statement:

INCLUDE=GERHND

Furthermore, these user defined error routines may call the system defined error loggingprocedure GERLOGC.

The third parameter of this procedure represents the error file where error messages willbe written. This file must be declared with SSF format.

If this third parameter is not present, a message will be written on the terminal.

ERROR LOGGING GKCL, GKOP, WSOP, WSAC

CALL "GERLOGC" USING ERRNR, FCTID [, ERRFIL].

Input parameters:

77 ERRNR COMP-2. Error number77 FCTID COMP-2. Function identificationSELECT ERRFIL ASSIGN TO ifn WITH SSF. Error fileFD ERRFIL.

4.5.6 Cell Array And Pixel Array Functions

The representation of CELL ARRAY and PIXEL ARRAY allows the user of the routinesrequiring a cell array parameter to pass any of the array as an argument. Two examplesshould make this clear.

Certainly the user can pass an entire two-dimensional array. In this case the number ofrows and columns of the cell array are the same as the number of rows and columns ofthe portion passed:

01 COL. 02 COLI OCCURS dimY. 03 COLIA OCCURS dimX.

CALL "GCA" USING X1, Y1, X2, Y2, DIMX, DIMY, 1, 1, DIMX, DIMY, COLIA (1,1)

(1,1) (2,1) (3,1) (DIMX,1) (1,2) (2,2) (3,2) (DIMX,2) . . . . . . . . . . . . (1,DIMY) (2,DIMY) (3,DIMY) (DIMX,DIMY)


4-10 47 A2 40UL Rev01

IMPORTANT

Note the difference between FORTRAN and COBOL programs in thedeclarations of the colour index array in COBOL programs. DimYwhich represents the number of rows is indicated first and dimXwhich represents the number of columns is indicated second.

To use an arbitrary portion of an array, the user passes in addition to the cell array andits dimension the indices of the upper left corner of the portion as the starting addressand the number of rows and columns of the portion to be passed. The area inside theasterisks is the cell array being passed:

CALL "GCA" USING X1, Y1, X2, Y2, DIMX, DIMY, STARTX, STARTY, DX, DY, COLIA (1,1).

For example, with STARTX = 3, STARTY = 6, DX = 2, DY = 3 we get:

(1,1) (2,1) (3,1) (4,1) ... (DIMX,1) (1,2) (2,2) (3,2) (4,2) ... (DIMX,2) . . . . . ********************** . (1,6) (2,6) * (3,6) (4,6) * ... (DIMX,6) (1,7) (2,7) * (3,7) (4,7) * ... (DIMX,7) (1,8) (2,8) * (3,8) (4,8) * ... (DIMX,8) . . ********************** . . . . (1,DIMY) (2,DIMY) (3,DIMY) (4,DIMY) ... (DIMX,DIMY)

4.5.7 COBOL Interface Under TDS

4.5.7.1 Introduction

This section contains instructions for writing a TDS generation program and transactionsusing GKS under TDS. It assumes the reader is a competent COBOL and TDSprogrammer and therefore lists only the unusual features of a GKS program under TDS.

For further information on TDS, refer to the TDS Programmer's manual 47 A2 03UT.

4.5.7.2 TDS Generation Program

The TDS generation program is composed of the following sections:

• TDS section• Input-output section• Transaction section.

Language Bindings

47 A2 40UL Rev01 4-11

TDS section

The formatted message length defines the maximum size of the space used to saveFORMS control structure and GKS tables: GKS uses a maximum of 9 kbytes. The usermust indicate the maximum size used by each. We advise a high value (for example24576).

The statements:

USE FORMS [NO IMPLICIT RELEASE].FORMATTED MESSAGE-LENGTH IS integer-14 MAXIMUM.

are mandatory.

The clause ``NO IMPLICIT RELEASE`` enables the user to keep the tables of GKSactive between two transactions instead of reactivating them at the beginning of eachnew transaction. If this clause is omitted, tables of GKS are released implicitly by thesystem at the end of each transaction.

If the application has its own error handling, it must add the statement:

USE GERHND.

INPUT-OUTPUT Section

If the application has an error file, the file must be declared in this section. It must bedeclared with SSF format.

In TDS, all the users of GKS can write on this file, so use of this file is not recommended.We advise the user to write error messages on the terminal by calling the function``GOPKSC`` without parameters.

4.5.7.3 Message

For each output primitive, GKS issues one or more SEND statements, the last of thembeing a SEND statement with EMI. A SEND after a SEND with EMI will degradeperformance, so it is advisable to call only one output primitive function per TPR.

It is possible to issue a SEND statement when GKS is opened. But after a SENDstatement with EGI, it is not possible to call a GKS function before the correspondingRECEIVE.


4-12 47 A2 40UL Rev01

47 A2 40UL Rev01 5-1

5. The GKS Function Interface

The heading of each function specifies the GKS function's name and the GKS state inwhich the function may be used. For each GKS function used by FORTRAN and COBOLprograms, the corresponding FORTRAN subroutines invocation is given. Use the tableof paragraph 4.5.2 for correspondence of data formats between FORTRAN 77 andCOBOL programs. When the entry points are different in FORTRAN and COBOLprograms, the two entry points are specified with their parameters. The effect of thefunction and the errors which can occur are described in more detail.

5.1 CONTROL FUNCTIONS

OPEN GKS GKCL

FORTRAN program only:

CALL GOPKS (ERRFIL)

Input parameters:

ERRFIL Error message file (logical unit Integer number of open FORTRAN file)

COBOL program only:

CALL "GOPKSC" [ USING ERRFIL ]

Input parameters:

SELECT ERRFIL ASSIGN TO ifn WITH SSF File errorFD ERRFIL.

Effect:

GKS is set into the operating state GKOP = "`GKS open". The GKS state list is allocatedand initialized as indicated in 6.4. The GKS description table and workstation descriptiontables are made available.


5-2 47 A2 40UL Rev01

The entry 'error file' in the GKS error state list is set to the value specified by theparameter.

The function ensures the domain exists in the site and the memory needed can beallocated. If not, error 950 is returned.

References:

3.6, 3.7, 4.5.3.

Errors:

1 GKS not in proper state: GKS must be in state GKCL.950 Initialization error.960 Number of arguments is invalid.

CLOSE GKS GKOP

CALL GCLKS

Parameters:

None.

Effect:

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 GKSbuffers are released and all GKS files and closed.

Note that GKS can be reopened by invoking the function OPEN GKS.

References:

3.6, 3.7.

Errors:

2 GKS not in proper state: GKS must be in state GKOP.960 Number of arguments is invalid.

The GKS Function Interface

47 A2 40UL Rev01 5-3

OPEN WORKSTATION GKOP

CALL GOPWK (WKID, CONID, WTYPE)

Input parameters:

WKID Workstation identifier IntegerCONID Connection identifier (must Integer be zero)WTYPE Workstation type Integer

Effect:

If GKS is in operating state GKOP, it is set into the state WSOP = 'one workstationopen'. The workstation state list is allocated and initialized as indicated in paragraph 6.5.The workstation identifier is added to the set of open workstations in the state list.

Note that error 951 occurs when the workstation type does not correspond to therequested workstation type. The parameter connection identifier must be zero.

References:

3.4.2, 3.6.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.22 Specified workstation type is invalid.23 Specified workstation type does not exist.951 This workstation is not of the type requested.952 Only one output workstation can be open.960 Number of arguments is invalid.

CLOSE WORKSTATION WSOP, WSAC

CALL GCLWK (WKID)

Input parameters:

WKID Workstation identifier Integer

Effect:

The workstation state list is deallocated. The workstation identifier is deleted from the setof active workstation in the GKS state list. GKS is set into operating state GKOP.

References:

3.4.2, 3.6.


5-4 47 A2 40UL Rev01

Errors:

6 GKS must be either in state WSOP or in state WSAC.25 Specified workstation is not open.29 Specified workstation is active.960 Number of arguments is invalid.

ACTIVATE WORSTATION WSOP

CALL GACWK (WKID)

Input parameters:


Effect:

GKS is set into the operating state WSAC = 'At least one workstation active'. Thespecified workstation is marked active in the workstation state list. The workstationidentifier is added to the set of active workstation in the GKS state list.

References:

3.4.2, 3.6.

Errors:

6 GKS must be either in state WSOP or in state WSAC.25 Specified workstation is not open.953 Only one output workstation can be active.960 Number of arguments is invalid.

DEACTIVATE WORKSTATION WSAC

CALL GDAWK (WKID)

Input parameters:


Effect:

The specified workstation is marked inactive in the workstation state list. The workstationidentifier is deleted from the set of active workstations in the GKS state list. GKS is setinto the operating state WSOP = 'AT least one workstation open' if no workstationremains active.

Note that while a workstation is inactive, primitives are not sent to it.


47 A2 40UL Rev01 5-5

References:

3.4.2, 3.6.

Errors:

3 GKS not in proper state: GKS must be in state WSAC.30 Specified workstation is not active.960 Number of arguments is invalid.

CLEAR WORKSTATION WSOP, WSAC

CALL GCLRWK (WKID, COFL)

Input parameters:

WKID Workstation identifier IntegerCOFL Control flag (GCONDI, GALWAY) Integer

Effect:

The display surface is cleared.

Note that the control flag is not used.

Errors:

6 GKS must be either in state WSOP or in state WSAC.25 Specified workstation is not open.960 Number of arguments is invalid.

UPDATE WORKSTATION WSOP, WSAC

CALL GUWK (WKID, REGFL)

Input parameters:

WKID Workstation identifier IntegerREGFL Regeneration flag Integer (GSUPP, GPERFO)

Effect:

All the deferred actions for the specified workstation are executed.

Note that the supported terminals have no deferred actions, so this function has noeffect.


5-6 47 A2 40UL Rev01

Errors:


ESCAPE GKOP, WSOP, WSAC

CALL GESC (FCTID, LDR, DATREC)

Input parameters:

FCTID Function identification IntegerLDR Dimension of data record IntegerDATREC (LDR) Data record Character*80

Effect:

The specified non-standard specific escape function is invoked.

Note that this implementation does not support any escape function. The appropriateerror code is returned.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.180 Specified function is not supported.960 Number of arguments is invalid.


47 A2 40UL Rev01 5-7

5.2 OUTPUT FUNCTIONS

POLYLINE WSAC

CALL GPL (N, PX, PY)

Input parameters:

N Number of points IntegerPX(N), PY(N) Position of points in WC Real

Effect:

A sequence of connected straight lines is generated, starting from the first point andending at the last point. The current values of the polyline attributes, as given by the GKSstate list (see 6.4), are bound to the primitive. The polyline attributes are listed in 3.3.3.

Note that the number of points is limited to 1000.

References:

3.3.1, 3.3.3, 3.3.4.

Errors:

3 GKS not in proper state: GKS must be in state WSAC.100 Number of points is invalid.960 Number of arguments is invalid.

POLYMARKER WSAC

CALL GPM (N, PX, PY)

Input parameters:


Effect:

A sequence of markers is generated to identify all the given positions. The current valuesof the polymarker attributes, as given by the GKS state list (see 6.4), are bound to theprimitive. The polymarker attributes are listed in 3.3.4.

Note that the number of point is limited to 1000.


5-8 47 A2 40UL Rev01

References:

3.3.1, 3.3.3, 3.3.5.

Errors:


TEXT WSAC


CALL GTX (PX, PY, CHARS)

Input parameters:

PX, PY Text position in WC C RealCHARS String of characters Character*(*)

COBOL program only:

CALL ``GTXS'' USING PX, PY, LG, CHARS.

Input parameters:

77 PX COMP-9. Text position in WC77 PY COMP-9.77 LG COMP-2. Length of the text77 CHARS PIC X(n). String of characters

Effect:

A character string is generated. The current values of the text attributes, as given by theGKS state list (see 6.4) are bound to the primitive. The text attributes are listed in Thetext position is given in WC and transformed by the current normalization transformation.

Note that text is clipped in a way that depends on the text precision as defined by therelevant text bundle. Only the first 255 characters can be considered.

References:

3.3.1, 3.3.3, 3.3.6, 4.5.4.

Errors:

3 GKS not in proper state: GKS must be in state WSAC.101 Invalid code in string.960 Number of arguments is invalid.


47 A2 40UL Rev01 5-9

FILL AREA WSAC

CALL GFA (N, PX, PY)

Input parameters:


Effect:

A FILL AREA primitive is generated. The current values of the fill area attributes, asgiven by the GKS state list (see 6.4), are bound to the primitive. The fill area attributesare listed in 3.3.3.

The polygon defined by the points is filled according to the fill area interior style currentlyselected (either via the fill area bundle or individually, depending upon the correspondingASF). The boundary is drawn for interior style HOLLOW and is not drawn for otherinterior styles. If parts of the area are clipped, the resulting new boundaries become partof the area boundaries. Multiple subareas may be generated (see Figure 5-1).

Note that the number of points is limited to 500. On ANDERSON JACOBSON,boundaries are always drawn.

References:

3.3.1, 3.3.3, 3.3.7.

Errors:


W I N D O Wresul t ing AREAs af terc l ipp ing a t the WINDOW

points added to polygon

Figure 5-1. Examples of FILL AREA clipping


5-10 47 A2 40UL Rev01

The interior of a polygon is defined in the following way:

P : points to be testedN: intersect ion count

1

Figure 5-2. Area inside a polygon

For a given point, create a straight line starting at that point and going yo infinity. If thenumber of intersections between the straight line and the polygon is odd, the point iswithin the polygon: otherwise it is outside. If the straight line passes a polygon vertextangentially, the intersection is not affected.

CELL ARRAY WSAC

CALL GCA (PX, PY, QX, QY, DIMX, DIMY, NCS, NRS, DX, DY, COLIA)

Input parameters:

PX, PY, QX, QY Two points, (P,Q) in WC RealDIMX, DIMY Dimensions of colour index Integer arrayNCS, NRS Start column and start row IntegerDX, DY No. of columns, no. of rows Integer usedCOLIA (DIMX, DIMY) Colour index array Integer

Effect:

A CELL ARRAY primitive is generated using the cell rectangle corners, the dimensionsof the colour index array and the colour index array. A rectangle, which is taken to bealigned with the world coordinate axes is defined by the points P and Q. This rectangle isconceptually divided into a grid in DXxDY cells. |PX-QX|/ DX and a height of |PY-QY|/DY, Where (PX, PY) are the coodinates of the corner point P and (QX, QY) are thecoordinates of the corner point Q. The colour of each cell is specified by the index of thecorresponding element of the colour index array. If an index is not present in the colourtable on a workstation, index number 1 is used on that workstation. The user can passany portion of the array as an argument. He passes in addition to the cell array and itsdimension, the indices of the upper left corner of the portion as the starting address andthe number of rows and columns of the position to be passed.

Note that dimension of cell array is limited to 500 x 500.


47 A2 40UL Rev01 5-11

References:

3.3.1, 3.3.3, 3.3.8, 4.4.2, 4.5.6.

Errors:

3 GKS not in proper state: GKS must be in state WSAC.84 Dimensions of colour array are invalid.960 Number of arguments is invalid.

GENERALIZED DRAWING PRIMITIVE (GDP) WSAC

CALL GGDP (N, PX, PY, PRIMID, LDR, DATREC)

Input parameters:

N Number of points IntegerPX (N), PY (N) Position of points in WC RealPRIMID GDP dentifier IntegerLDR Dimension of data record IntegerDATREC (LDR) Data record Integer

Effect:

A Generalized Drawing Primitive (GDP) of the type indicated by the GDP identifier isgenerated on the basis of the given points and the GDP data record. the current valuesof the entries in the GKS state list (see 6.4) for the sets of polyline, polymarker, text or fillarea attributes are bound to the primitive. These attributes are listed in 3.3.3. When theGDP generates output at the workstation, zero or more of the sets of attributes are used.

These are the sets of attributes most appropriate for the specified GDP function and areselected for the GDP as part of the definition of the GDP. (They are defined in theworkstation description table). There are seven GDPs which are listed below.

References:

3.3.1, 3.3.2, 3.3.3, 3.3.9.

Errors:

3 GKS not in proper state: GKS must be in state WSAC.100 Number of points is invalid.102 Generalized drawing primitive identifier is invalid.103 Content of GDP data record is invalid.960 Number of arguments is invalid.

BOX (GDP 01)


5-12 47 A2 40UL Rev01

Parameters:

The GDP identifier must be one.Other parameters are not used.

Effect:

This GDP draws the current clipping rectangle.The polyline set of attributes is used.

AXIS (GDP 02)

Parameters:

The GDP identifier must be two.PX and PY indicate the steps of graduation.Other parameters are not used.

Effect:

This GDP draws graduate axes in the current clipping rectangle. The steps on each axisare given in parameter (PX, PY). If PX = 0 or PY = 0, the step is calculated depending onworld coordinates.

The polyline set of attibutes is used.

If it is impossible to draw the axis at the origin, we put them at the left and bottom with aplace reserved for annotations.

AUTOSCALE (GDP 03)

Parameters:

The GDP identifier must be three.N indicates the number of points.PX (N), PY (N) indicates the coordinates of two points.Data record is composed of two integers:

• SCAL = DATREC(1) indicates if the window is centered (SCAL = 1) or not (SCAL = 0).• NBTRAN = DATREC(2) indicates the number of transformations.

Effect:

GKS computes a window of the given normalization transformation including all thepoints given in parameters. The window can be centered or not in (0,0) depending on thevalue of SCAL.

CIRCLE (GDP 04)

Parameters:

The GDP identifier must be four.N must be two.PX (2), PY (2) indicate the coordinates of the center and a point of the circle.Other parameters are not used.


47 A2 40UL Rev01 5-13

Effect:

GKS generates a circle defined by a center and a point fill area set of attributes is used.

If the radius of the circle is too small (< 3 pixels) or if the circle is degenerated in too flatan ellipse, a dot is drawn.

Note that on ANDERSON JACOBSON, interior style hollow is always used.

ARC (GDP 05)

Parameters:

The GDP identifier must be five.N must be three.PX (3), PY(3) indicate coordinates of beginning, intermediate and ending points.Other parameters are not used.

Effect:

GKS generates an arc defined by three points, beginning from the first point, passingthrough the second point and ending at the third point.

If the three points are identical, a dot is drawn.

If two points are identical, a circle is drawn with its diameter defined by the two differentpoints.

The polyline set of attributes is used.

Note that on ANDERSON JACOBSON, linetype 1 is always used.

PIE (GDP 06)

Parameters:

The GDP identifier must be six.N must be three.PX (3), PY (3) indicate coordinates of beginning, intermediate and ending points.Other parameters are not used.

Effect:

GKS generates a polygonal area composed of an arc defined by three points and tworadii.

When the three points are aligned, a polyline defined by these three points is drawn.

The fill area set of attributes is used.

Note that on ANDERSON JACOBSON, interior sytle hollow is always used.

CHORD (GDP 07)


5-14 47 A2 40UL Rev01

Parameters:

The GDP identifier must be seven.N must be three.PX (3), PY (3) indicate coordinates of beginning, intermediate and ending points.Other parameters are not used.

Effect:

GKS generates a polygonal area composed of an arc defined by three points and achord.

When the three points are aligned, a polyline defined by these three points is drawn. Thefill area set of attributes is used.

Note that on ANDERSON JACOBSON, interior style hollow is always used.


47 A2 40UL Rev01 5-15

5.3 OUTPUT ATTRIBUTES

5.3.1 Workstation Independent Primitive Attributes

SET POLYLINE INDEX GKOP, WSOP, WSAC

CALL GSPLI (INDEX)

Input parameters:

INDEX Polyline index Integer

Effect:

The 'current polyline index' entry in the GKS state list is set to the value specified by theparameter. This value is used when creating subsequent POLYLINE output primitives.

References:

3.3.3, 3.3.4.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.6 GKS must be either in state WSOP on in state WSAC.960 Number of arguments is invalid.

SET LINETYPE GKOP, WSOP, WSAC

CALL GSLN (LTYPE)

Input parameters:

LTYPE Linetype Integer

Effect:

The 'current linetype' entry in the GKS state list is set to the value specified by theparameter. This value is used for the display of subsequent POLYLINE output primitives,created when the 'current linetype ASF' entry in the GKS state list is INDIVIDUAL. Thisvalue does not affect the display of subsequent POLYLINE output primitives, createdwhen the 'current linetype ASF' entry in the GKS state list is BUNDLED.


5-16 47 A2 40UL Rev01

Linetype values produce linetypes as indicated:

1. solid line2. dashed line3. dotted line4. dashed-dotted line5. implementation dependent

If the specified linetype is not available on a workstation, linetype 1 is used on thatworkstation.

References:

3.3.3, 3.3.4.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.6 GKS must be either in state WSOP or in state WSAC.960 Number of arguments is invalid.

SET LINEWIDTH SCALE FACTO GKOP, WSOP, WSAC

CALL GSLWSC (LWIDTH)

Input parameters:

LWIDTH Linewidth scale factor Real

Effect:

The current 'linewidth scale factor' entry in the GKS state list is set to the value specifiedby the parameter. This value is used for the display of subsequent POLYLINE outputprimitives, created when the 'current linewidth scale factor ASF' entry in the GKS statelist is INDIVIDUAL. This value does not affect the display of subsequent POLYLINEoutput primitives, created when the 'current linewidth scale factor ASF' entry in the GKSstate list is BUNDLED.

The linewidth scale factor is applied to the nominal linewidth on a workstation: the resultis mapped by the workstation to the nearest available linewidth.

References:

3.3.3, 3.3.4.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.960 Number of arguments is invalid.


47 A2 40UL Rev01 5-17

SET POLYLINE COLOUR INDEX GKOP, WSOP, WSAC

CALL GSPLCI (COLI)

Input parameters:

COLI Polyline colour index Integer

Effect:

The 'current polyline colour index' entry in the GKS state list is set to the value specifiedby the parameter. This value is used for the display of subsequent POLYLINE outputprimitives, created when the 'current polyline colour index ASF' entry in the GKS state listis INDIVIDUAL. This value does not affect the display of subsequent POLYLINE outputprimitives, created when the 'current polyline colour index ASF' entry in the GKS state listis BUNDLED.

The colour index is a pointer into the colour tables of the workstation. If the specifiedcolour index is not present in a workstation colour table, colour index 1 is used on thatworkstation.

References:

3.3.3, 3.3.4.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.85 Colour index is less than zero.960 Number of arguments is invalid.

SET POLYMARKER INDEX GKOP, WSOP, WSAC

CALL GSPMI (INDEX)

Input parameters:

INDEX Polymarker index Integer

Effect:

The 'current polymarker index' entry in the GKS state list is set to the value specified bythe parameter. This value is used when creating subsequent POLYMARKER outputprimitives.

References:

3.3.3, 3.3.5.


5-18 47 A2 40UL Rev01

Errors:


SET MARKER TYPE GKOP, WSOP, WSAC

CALL GSMK (MTYPE)

Input parameters:

MTYPE Marker type Integer

Effect:

The 'current marker type' entry in the GKS state list is set to the value specified by theparameter. This value is used for the display of subsequent POLYMARKER outputprimitive, created when the 'current marker type ASF' entry in the GKS state list isINDIVIDUAL. This value does not affect the display of subsequent POLYMARKERoutput primitives, created when the 'current marker type ASF' entry in the GKS state listis BUNDLED.

Marker type values produce centred symbols as indicated.

1. .2. +3. *4. 05. X6. (or greater) application dependent

Marker type 1 is always displayed as the smallest displayable dot. If the specified markertype is not available on a workstation, marker type 3 (*) is used on that workstation.

References:

3.3.3, 3.3.3.

Errors:



47 A2 40UL Rev01 5-19

SET MARKER SIZE SCALE FACTOR GKOP, WSOP, WSAC

CALL GSMKSC (MSZSF)

Input parameters:

MSZSF Marker size scale factor Real

Effect:

The 'current marker size scale factor' entry in the GKS state list is set to the valuespecified by the parameter. This value is used for the display of subsequentPOLYMARKER output primitives, created when the current marker size scale factorASF' entry in the GKS state list is INDIVIDUAL. This value does not affect the display ofsubsequent POLYMARKER output primitives, created when the 'current marker sizescale factor ASF' entry in the GKS state list is BUNDLED.

The marker size scale factor is applied to the nominal marker size on a workstation; theresult is mapped by the workstation to the nearest available marker size.

References:

3.3.3, 3.3.5.

Errors:


SET POLYMARKER COLOUR INDEX GKOP, WSOP, WSAC

CALL GSPMCI (COLI)

Input parameters:

COLI Polymarker colour index Integer

Effect:

The 'current polymarker colour index' entry in the GKS state list is set to the valuespecified by the parameter. This value is used for the display of subsequentPOLYMARKER output primitives, created when the 'current polymarker colour indexASF' entry in the GKS state list is INDIVIDUAL. This value does not affect the display ofsubsequent POLYMARKER output primitives, created when the 'current polymarkercolour index ASF' entry in the GKS state list is BUNDLED.

The colour index is a pointer into the colour tables of the workstations. If the specifiedcolour index is not present in a workstation colour table, colour index 1 is used on thatworkstation.

References:

3.3.3, 3.3.5.


5-20 47 A2 40UL Rev01

Errors:


SET TEXT INDEX GKOP, WSOP, WSAC

CALL GSTXI (INDEX)

Input parameters:

INDEX Text index Integer

Effect:

The 'current text index' entry in the GKS state list is set to the value specified by theparameter. This value is used when creating subsequent output primitives.

References:

3.3.3, 3.3.6.

Errors:


SET TEXT FONT AND PRECISION GKOP, WSOP, WSAC

CALL GSTXFP (FONT, PREC)

Input parameters:

FONT Text font IntegerPREC Text precision (GSTEP, GCHARP, Integer GSTRKP)

Effect:

The 'current text font and precision' entry in the GKS state list is set to the valuespecified by the parameter. This value is used for the display of subsequent TEXT outputprimitives, created when the 'current text font and precision ASF' entry in the GKS statelist is INDIVIDUAL. This value does not affect the display of subsequent TEXT outputprimitives, created when the 'current text font and precision ASF' entry in the GKS statelist is BUNDLED.


47 A2 40UL Rev01 5-21

Text font and precision is a single text aspect; a particular text font can be available atsome, but not necessarily all, precisions. The text precision value determines the fidelitywith which the other text aspects are used. The values of text precision, in order ofincreasing fidelity, are STRING, CHAR and STROKE (see 3.3.6).

If the specified text font and precision is not available on a workstation, the value (1:STRING) is used on that workstation.

References:

3.3.3, 3.3.6.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.70 ext font is less than or equal to zero.960 Number of arguments is invalid.

SET CHARACTER EXPANSION FACTOR GKOP, WSOP, WSAC

CALL GSCHXP (CHXP)

Input parameters:

CHXP Character expansion factor Real

Effect:

The 'current character expansion factor' entry in the GKS state list is set to the valuespecified by the parameter. This value is used for the display of subsequent TEXT outputprimitives, created when the 'current character expansion factor ASF' entry in the GKSstate list is INDIVIDUAL. This value does not affect the display of subsequent TEXToutput primitives, created when the 'current character expansion factor ASF' entry in theGKS state list is BUNDLED.

References:

3.3.3, 3.3.6.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.72 Character expansion factor is less than or equal to zero.960 Number of arguments is invalid.


5-22 47 A2 40UL Rev01

SET CHARACTER SPACING GKOP, WSOP, WSAC

CALL GSCHSP (CHSP)

Input parameters:

CHSP Character spacing Real

Effect:

The 'current character spacing' entry in the GKS state list is set to the value specified bythe parameter. This value is used for the display of subsequent TEXT output primitives,created when the 'current character spacing ASF' entry in the GKS state list isINDIVIDUAL. This value does not affect the display of subsequent TEXT outputprimitives, created when the 'current character spacing ASF' entry in the GKS state list isBUNDLED.

References:

3.3.3, 3.3.6.

Errors:


SET TEXT COLOUR INDEX GKOP, WSOP, WSAC

CALL GSTXCI (COLI)

Input parameters:

COLI Text colour index Integer

Effect:

The 'current text colour index' entry in the GKS state list is set to the value specified bythe parameter. This value is used for the display of subsequent TEXT output primitives,created when the 'current text colour index ASF' entry in the GKS state list isINDIVIDUAL. This value does not affect the display of subsequent TEXT outputprimitives, created when the 'current text colour index ASF' entry in the GKS state list isBUNDLED. The colour index is a pointer into the colour tables of the workstations. If thespecified colour index is not present in a workstation colour table, colour index 1 is usedon that workstation.

References:

3.3.3, 3.3.6.

Errors:


SET CHARACTER HEIGHT


47 A2 40UL Rev01 5-23

GKOP, WSOP, WSAC

CALL GSCHH (CHH)

Input parameters:

CHH Character height Real

Effect:

The 'current character height' entry in the GKS state list is set to the value specified bythe parameter. This value is used when creating subsequent TEXT output primitives.

References:

3.3.3, 3.3.6.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.73 Character height is less than or equal to zero.960 Number of arguments is invalid.

SET CHARACTER UP VECTOR GKOP, WSOP, WSAC

CALL GSCHUP (CHUX, CHUY)

Input parameters:

CHUX, CHUY Character up vector (WC) Real

Effect:

The 'current character up vector' entry in the GKS state list is set to the value specifiedby the parameter. This value is used when creating subsequent TEXT output primitives.

References:

3.3.3, 3.3.6.


5-24 47 A2 40UL Rev01

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.74 Length of character up vector is zero.960 Number of arguments is invalid.

SET TEXT PATH GKOP, WSOP, WSAC

CALL GSTXP (TXP)

Input parameters:

TXP Text path (GRIGHT, GLEFT, GUP, Integer GDOWN)

Effect:

The 'current text path' entry in the GKS state list is set to the value specified by theparameter. This value is used when creating subsequent TEXT output primitives.

Note that a change in the value of 'current text path' may make the value of the 'currenttext alignment' entry inappropriate.

References:

3.3.3, 3.3.6.

Errors:


SET TEXT ALIGNMENT GKOP, WSOP, WSAC

CALL GSTXAL (TXALH, TXALV)

Input parameters:

TXALH Text alignment horizontal Integer (GAHNOR, GALEFT, GACENT, GARITE)TXALV Text alignment vertical Integer (GAVNOR, GATOP, GACAP, GABASE, GABOTT)

Effect:

The 'current text alignment' entry in the GKS state list is set to the value specified by theparameter. This value is used when creating subsequent TEXT output primitives. Textalignment has two components: horizontal and vertical.


47 A2 40UL Rev01 5-25

References:

3.3.3, 3.3.6.

Errors:


SET FILL AREA INDEX GKOP, WSOP, WSAC

CALL GSFAI (INDEX)

Input parameters:

INDEX Fill area index Integer

Effect:

The 'current fill area index' entry in the GKS state list is set to the value specified by theparameter. This value is used when creating subsequent FILL AREA output primitives.

References:

3.3.3, 3.3.7.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.75 Fill area index is invalid.960 Number of arguments is invalid.

SET FILL AREA INTERIOR STYLE GKOP, WSOP, WSAC

CALL GSFAIS (INTS)

Input parameters:

INTS Fill area interior style Integer (GHOLLO, GSOLID, GPATTR, GHATCH)


5-26 47 A2 40UL Rev01

Effect:

The 'current fill area interior style' entry in the GKS state list is set to the value specifiedby the parameter. This value is used for the display of subsequent FILL AREA outputprimitives, created when the 'current fill area interior style ASF' entry in the GKS state listis INDIVIDUAL. This value does not affect the display of subsequent FILL AREA outputprimitives, created when the 'current fill area interior style ASF' entry in the GKS state listis BUNDLED.

The fill area interior style is used to determine in what style the area is filled and thepossible values are: HOLLOW, SOLID, PATTERN and HATCH (see 3.3.7).

If the requested interior style is not available on a workstation, HOLLOW is used on thatworkstation.

References:

3.3.3, 3.3.7.

Errors:


SET FILL AREA STYLE INDEX GKOP, WSOP, WSAC

CALL GSFASI (STYLI)

Input parameters:

STYLI Fill area style index Integer

Effect:

The 'current fill area style index' entry in the GKS state list is set to the value specified bythe parameter. This value is used for the display of subsequent FILL AREA outputprimitives, created when the 'current fill area style index ASF' entry in the GKS state listis INDIVIDUAL. This value does not affect the display of subsequent FILL AREA outputprimitives, created when the 'current fill area style index ASF' entry in the GKS state listis BUNDLED.

For interior styles HOLLOW and SOLID, the style index value is unused.

For interior styles PATTERN or HATCH, its values determine which of a number ofworkstation dependent pattern or hatch styles is used.

If the requested interior style index is not available on a workstation, style index 1 is usedon that workstation.


47 A2 40UL Rev01 5-27

References:

3.3.3, 3.3.7.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.78 Style (pattern or hatch) index is less than or equal to zero.960 Number of arguments is invalid.

SET FILL AREA COLOUR INDEX GKOP, WSOP, WSAC

CALL GSFACI (COLI)

Input parameters:

COLI Fill area index Integer

Effect:

The 'current fill area colour index' entry in the GKS state list is set to the value specifiedby the parameter. This value is used for the display of subsequent FILL AREA outputprimitives, created when the 'current fill area interior style ASF' entry in the GKS state listis INDIVIDUAL. This value does not affect the display of subsequent FILL AREA outputprimitives, created when the 'current fill area colour index ASF' entry in the GKS state listis BUNDLED.

The colour index is a pointer into the colour tables of the workstations. If the specifiedcolour index is not present in a workstation colour table, colour index 1 is used.

References:

3.3.3, 3.3.7.

Errors:


SET PATTERN SIZE GKOP, WSOP, WSAC

CALL GSPA (SZX, SZY)

Input parameters:

SZX, SZY Pattern size Real


5-28 47 A2 40UL Rev01

Effect:

The 'current pattern size' entry in the GKS state list is set to the value specified by theparameter. When the currently selected (either via the fill area bundle or individually,depending on the corresponding ASF) fill area interior style is PATTERN, this value isused, where possible, in conjunction with the 'current pattern reference point' entry in theGKS state list for displaying the FILL AREA output primitives.

Note that in this implementation, the workstations do not support pattern size. Error code958 is returned.

References:

3.3.3, 3.3.7.

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.81 Pattern size value is not positive.958 Pattern size and pattern reference point are not supported.960 Number of arguments is invalid.

SET PATTERN REFERENCE POINT GKOP, WSOP, WSAC

CALL GSPARF (RFX, RFY)

Input parameters:

RFX, RFY Pattern reference point Real

Effect:

The 'current pattern reference point' entry in the GKS state list is set to the valuespecified by the parameter. When the currently selected (either via the fill area bundle orindividually, depending upon the corresponding ASF) fill area interior style is PATTERN,this value is used, where possible, in conjunction with the 'current pattern size' entry inthe GKS state list for displaying the FILL AREA output primitives.

Note that in this implementation, the workstations do not support pattern reference point.Error code 958 is returned.

References:

3.3.3, 3.3.7.


47 A2 40UL Rev01 5-29

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.958 Pattern size and pattern reference point are not supported.960 Number of arguments is invalid.

SET ASPECT SOURCE FLAGS GKOP, WSOP, WSAC

CALL GSASF (LASF)

Input parameters:

LASF (13) List of aspect source flags Integer (GBUNDL, GINDIV)

1 = linetype ASF2 = linewidth scale factor ASF3 = polyline colour index ASF4 = marker type ASF5 = marker size scale factor ASF6 = polymarker colour index ASF7 = text font and precision ASF8 = character expansion factor ASF9 = character spacing ASF10 = text colour index ASF11 = fill area interior style ASF12 = fill area style index ASF13 = fill area colour index ASF

Effect:

The Aspect Source Flags (ASFs) in the GKS state list are set to the values indicated bythe parameter.

Reference:

3.5.3

Errors:



5-30 47 A2 40UL Rev01

5.3.2 Workstation attributes (representation)

SET COLOUR REPRENSENTATION WSOP, WSAC

CALL GSCR (WKID, CI, CR, CG, CB)

Input parameters:

WKID Workstation identifier IntegerCI Colour index IntegerCR Red RealCG Green RealCB Blue Real

Effect:

In the colour table of the workstation state list, the given colour index is associated withthe specified colour. The colour is mapped by the workstation to the nearest available.

The colour table in the workstation state list has predefined entries taken from theworkstation description table; at least indices 0 and 1 are predefined for everyworkstation of category OUTPUT. Any table entry (including the predefined entries) maybe redefined with this function.

When output primitives are displayed, the colour index refers to an entry in the colourtable. If output primitives are displayed with a colour index that is not present in thecolour table, colour index 1 is used. The background colour is defined by colour index 0.

References:

3.3.3, 3.3.10.

Errors:

6 GKS must be either in state WSOP or in state WSAC.25 Specified workstation is not open.85 Colour index is less than zero.86 Colour index is invalid.88 Colour is outside range (O,1).960 Number of arguments is invalid.


47 A2 40UL Rev01 5-31

5.4 TRANSFORMATION FUNCTIONS

5.4.1 Normalization Transformation

SET WINDOW GKOP, WSOP, WSAC

CALL GSWN (TNR, XMIN, XMAX, YMIN, YMAX)

Input parameters:

TNR Transformation number IntegerXMIN, XMAX, Window limits in WC with RealYMIN, YMAX XMIN < XMAX, YMIN < YMAX

Effect:

The window limits entry of the specified normalization transformation in the GKS statelist is set to the value specified by the parameter.

Reference:

3.5.1

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.50 Transformation number is invalid.51 Rectangle definition is invalid.960 Number of arguments is invalid.

SET VIEWPORT GKOP, WSOP, WSAC

CALL GSVP (TNR, XMIN, XMAX, YMIN, YMAX)

Input parameters:

TNR Transformation number IntegerXMIN, XMAX Viewport limits in NDC RealYMIN, YMAX With XMIN < XMAX, YMIN < YMAX

Effect:

The viewport limits entry of the specified normalization transformation in the GKS list isset to the value specified by the parameter.


5-32 47 A2 40UL Rev01

Reference:

3.5.1

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.50 Transformation number is invalid.51 Rectangle definition is invalid.52 Viewport is not within the NDC unit square.960 Number of arguments is invalid.

SELECT NORMALIZATION TRANSFORMATION | GKOP, WSOP, WSAC

CALL GSELNT (TNR)

Input parameters:

TNR Transformation number Integer

Effect:

The 'current normalization transformation number' entry in the GKS state list is set to thevalue specified by the parameter.

Reference:

3.5.1

Errors:

8 GKS must be in one of the states GKOP, WSOP, WSAC.50 Transformation number is invalid.960 Number of arguments is invalid.

SET CLIPPING INDICATOR GKOP, WSOP, WSAC

CALL GSCLIP (CLSW)

Input parameters:

CLSW Clipping indicator Integer (GNCLIP, GCLIP)


47 A2 40UL Rev01 5-33

Effect:

The 'clipping indicator' entry in the GKS state list is set to the value specified by theparameter.

Reference:

3.5.2

Errors:


5.4.2 Workstation Transformation

SET WORKSTATION WINDOW WSOP, WSAC

CALL GSWKWN (MKID, XMIN, XMAX, YMIN, YMAX)

Input parameters:

WKID Workstation identifier IntegerXMIN, XMAX, Workstation window limits in RealYMIN, YMAX NDC with XMIN < XMAX, YMIN < YMAX

Effect:

The 'requested workstation window' entry in the workstation state list of the specifiedworkstation is set to the value specified by the parameter.

Reference:

3.5.3

Errors:

6 GKS must be either in state WSOP or in state WSAC.25 Specified workstation is not open.51 Rectangle definition is invalid.53 Workstation window is not within the NDC unit square.960 Number of arguments is invalid.


5-34 47 A2 40UL Rev01

SET WORKSTATION VIEWPORT WSOP, WSAC

CALL GSWKVP (WKID, XMIN, XMAX, YMIN, YMAX)

Input parameters:

WKID Workstation identifier IntegerXMIN, XMAX, Workstation viewport limits in RealYMIN, YMAX DC with XMIN < XMAX, YMIN < YMAX

Effect:

The 'requested workstation viewport' entry in the workstation state list of the specifiedworkstation is set to the value specified by the parameter.

Reference:

3.5.3

Errors:

6 GKS must be either in state WSOP or in state WSAC.25 Specified workstation is not open.51 Rectangle definition is invalid.54 Workstation viewport is not within the display space.960 Number of arguments is invalid.


47 A2 40UL Rev01 5-35

5.5 METAFILE FUNCTIONS

None of these functions are mandatory at level 0-a; they return the appropriate errormessage.

WRITE ITEM TO GKSM WSAC

CALL GWITM (WKID, TYPE, LDR, DATREC)

Input parameters:

WKID Workstation identifier IntegerTYPE Item type IntegerLDR Dimension of data record IntegerDATREC (LDR) Data record Character*80

Effect:

An item containing non-graphical data provided by the application program is written tothe GKSM. The parameters 'item data record' and 'iten data record length' define thedata to be output whilst 'item type' specifies its type.

Errors:

3 GKS not in proper state: GKS must be in state WSAC.959 Metafile functions are not supported.

GET ITEM TYPE FROM GKSM WSOP, WSAC

CALL GGTITM (WKID, TYPE, LDR)

Input parameters:


Output parameters:

TYPE Item type IntegerLDR Length of item data record Integer

Effect:

GKS inspects the type of the current item and the length of its data record in the GKSMand returns type and length back to the application program.


5-36 47 A2 40UL Rev01

Errors:

6 GKS must be either in state WSOP or in state WSAC.959 Metafile functions are not supported.

READ ITEM FROM GKSM WSOP, WSAC

CALL GRDITM (WKID, MLDR, LDR, DATREC)

Input parameters:

WKID Workstation identifier IntegerMLDR Dimension of data record Integer

Output parameters:

LDR Length of the data record IntegerDATREC (LDR) Data record Character*80

Effect:

GKS returns the current item on the GKSM back to the application program then makesthe next item in the metafile the current item. If the item data record length is greaterthan 'maximum item data record length', the excess parts of the item are lost.

Errors:


INTERPRET ITEM WSOP, WSAC

CALL GIITM (TYPE, LDR, DATREC)

Input parameters:

TYPE Item type IntegerLDR Dimension of data record IntegerDATREC (LDR) Data record Character*80

Effect:

The supplied item is interpreted. This causes appropriate changes in the set of GKSvariables and the generation of appropriate graphical output, as determined by themetafile specification.

Errors:



47 A2 40UL Rev01 5-37

5.6 INQUIRY FUNCTIONS

5.6.1 INTRODUCTION

Inquiry functions return values from the various state lists. The data types of the valuesand the default values of the state list entries are summarized in section 6. Errorsdetected by inquiry functions are reported through an error indicator parameter; the errorhandling procedure is not called.

5.6.2 Inquiry Function for Operating State Value

INQUIRE OPERATING STATE VALUE GKCL, GKOP, WSOP, WSACCALL GQOPS (OPSTA)

Output parameters:

OPSTA Operating state value Integer (GGKCL, GGKOP, GWSOP, WSAC, GSGOP)

Effect:

The operating state of GKS is returned.

References:

3.6.1, 3.6.2.

Errors:

None

5.6.3 Inquiry Functions for GKS Description Table

INQUIRE LEVEL OF GKS GKOP, WSOP, WSAC

CALL GQLVKS (ERRIND, LEVEL)


5-38 47 A2 40UL Rev01

Output parameters:

ERRIND Error indicator IntegerLEVEL Level of GKS (LOA, LOB, LOC, L1A, Integer L1B, L1C, L2A, L2B, L2C)

Effect:

If the inquired information is available, the error indicator is returned as 0 and values arereturned in the output parameters.

If the inquired information is not available, the level of GKS is returned as 0 and the errorindicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 6. 2.

Errors:

None.

INQUIRE LIST ELEMENT OF AVAILABLE WORKSTATION TYPES

GKOP, WSOP, WSAC

CALL GQEWK (N, ERRIND, NUMBER, WKTYP)

Input parameters:

N List element requested Integer

Output parameters:

ERRIND Error indicator IntegerNUMBER Number of workstation types IntegerWKTYP Nth element in list of Integer available workstation types

Effect:



47 A2 40UL Rev01 5-39

If the inquired information is not available, the number of workstation types is returned as0, the element of the list is returned as 0 and the error indicator is set to one of thefollowing error numbers to indicate the reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.902 List element or set member not available.960 Number of arguments is invalid.

References:

3. 4. 1, 3. 6. 2.

Errors:

None.

INQUIRE MAXIMUM NORMALIZATION TRANSFORMATION NUMBER

GKOP, WSOP, WSAC

CALL GQMNTN (ERRIND, MAXTNR)

Output parameters:

ERRIND Error indicator IntegerMAXTNR Max. norm. transformation number

Effect:


If the inquired information is not available, the maximum normalization transformationnumber is returned as 0 and the error indicator is set to one of the following errornumbers to indicate the reason for non-availability:


References:

3. 5. 1, 3. 6. 2.

Errors:

None


5-40 47 A2 40UL Rev01

5.6.4 Inquiry Functions for GKS State List

INQUIRE SET MEMBER OF OPEN WORKSTATIONS

GKOP, WSOP, WSAC

CALL GQOPWK (N, ERRIND, OL, WKID)

Input parameters:

N Set member requested Integer

Output parameters:

ERRIND Error indicator IntegerOL Number of open workstations IntegerWKID Nth member of set of open Integer workstations

Effect:


If the inquired information is not available, the number of open workstations is returnedas 0, the member of set of open workstations is returned as 0 and the error indicator isset to one of the following error numbers to indicate the reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.902 List element or set member not available.960 Number of arguments is invalid.

References:

3. 4. 2, 3. 6. 2.

Errors:

None.

INQUIRE POLYLINE INDEX GKOP, WSOP, WSAC

CALL GQPLI (ERRIND, INDEX)

Output parameters:

ERRIND Error indicator IntegerINDEX Polyline index Integer


47 A2 40UL Rev01 5-41

Effect:


If the inquired information is not available, the polyline index is returned as 0 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE POLYMARKER INDEX GKOP, WSOP, WSAC

CALL GQPMI (ERRIND, INDEX)

Output parameters:

ERRIND Error indicator IntegerINDEX PolylineT index Integer

Effect:


If the inquired information is not available, the polymarker index is returned as 0, and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.


5-42 47 A2 40UL Rev01

INQUIRE TEXT INDEX GKOP, WSOP, WSAC

CALL GQTXI (ERRIND, INDEX)

Output parameters:

ERRIND Error indicator IntegerINDEX Text index Integer

Effect:


If the inquired information is not available, the text index is returned as 0 and the errorindicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 3.

Errors:

None.

INQUIRE CHARACTER HEIGHT GKOP, WSOP, WSAC

CALL GQCHH ( ERRIND, CHH)

Output parameters:

ERRIND Error indicator IntegerCHH Character height Real

Effect:



47 A2 40UL Rev01 5-43

If the inquired information is not available, the character height is returned as 0 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE CHARACTER UP VECTOR GKOP, WSOP, WSAC

CALL GQCHUP (ERRIND, CHUX, CHUY)

Output parameters:

ERRIND Error indicator IntegerCHUX, CHUY character up vector (WC) Real

Effect:


If the inquired information is not available, the character up vector is returned as (0, 0)and the error indicator is set to one of the following error numbers to indicate the reasonfor non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.


5-44 47 A2 40UL Rev01

INQUIRE TEXT PATH GKOP, WSOP, WSAC

CALL GQTXP (ERRIND, TXP)

Output parameters:

ERRIND Error indicator IntegerTXP Text path (GRIGHT, GLEFT, GUP, GDOWN) Integer

Effect:


If the inquired information is not available, the text path is returned as -1 and the errorindicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE TEXT ALIGNMENT GKOP, WSOP, WSAC

CALL GQTXAL (ERRIND, TXALH, TXALV)

Output parameters:

ERRIND Error indicator IntegerTXALH Text alignment horizontal Integer (GAHNOR, GALEFT, GACENT, GARITE)TXALV Text alignment vertical Integer GAVNOR, GATOP, GACAP, GAHALF, GABASE, GABOTT)

Effect:


If the inquired information is not available, the text alignment is returned as (-1, -1) andthe error indicator is set to one of the following error numbers to indicate the reason fornon-availability:



47 A2 40UL Rev01 5-45

References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE FILL AREA INDEX GKOP, WSOP, WSAC

CALL GQFAI (ERRIND, INDEX)

Output parameters:

ERRIND Error indicator IntegerINDEX Fill area index Integer

Effect:


If the inquired information is not available, the fill area index is returned as 0 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE PATTERN SIZE GKOP, WSOP, WSAC

CALL GQPA (ERRIND, SZX, SZY)

Output parameters:

ERRIND Error indicator IntegerSZX, SZY Pattern size Real


5-46 47 A2 40UL Rev01

Effect:


If the inquired information is not available, the pattern size is returned as (0, 0) and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE PATTERN REFERENCE POINT

GKOP, WSOP, WSAC

CALL GQPARF (ERRIND, RFX, RFY)

Output parameters:

ERRIND Error indicator IntegerRFX, RFY Pattern reference point Real

Effect:


If the inquired information is not available, the pattern reference point is returned as (0,0) and the error indicator is set to one of the following error numbers to indicate thereason for non-availability:


References:

3. 3. 3, 3. 6. 2.


47 A2 40UL Rev01 5-47

Errors:

None.

INQUIRE PICK IDENTIFIER GKOP, WSOP, WSAC

CALL GQPKID (ERRIND, PCID)

Output parameters:

ERRIND Error indicator IntegerPCID Pick identifier Integer

Effect:


If the inquired information is not available, the pick identifier is returned as 0 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.956 Pick identifier is not supported960 Number of arguments is invalid.

References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE LINETYPE GKOP, WSOP, WSAC

CALL GQLN (ERRIND, LTYPE)

Output parameters:

ERRIND Error indicator IntegerLTYPE Linetype Integer

Effect:



5-48 47 A2 40UL Rev01

If the inquired information is not available, the linetype is returned as 0 and the errorindicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE LINEWIDTH SCALE FACTOR GKOP, WSOP, WSAC

CALL GQLWSC (ERRIND, LWIDTH)

Output parameters:

ERRIND Error indicator IntegerLWIDTH Linewidth scale factor Real

Effect:


If the inquired information is not available, linewidth scale factor is returned as 0 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.


47 A2 40UL Rev01 5-49

INQUIRE POLYLINE COLOUR INDEX GKOP, WSOP, WSAC

CALL GQPLCI (ERRIND, COLI)

Output parameters:

ERRIND Error indicator IntegerCOLI Polyline colour index Integer

Effect:


If the inquired information is not available, the colour index is returned as -1 and the errorindicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE MARKERTYPE GKOP, WSOP, WSAC

CALL GQMK (ERRIND, MTYPE)

Output parameters:

ERRIND Error indicator IntegerMTYPE Marker type Integer

Effect:


If the inquired information is not available, the marker type is returned as 0 and the errorindicator is set to one of the following error numbers to indicate the reason for non-availability:



5-50 47 A2 40UL Rev01

References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE MARKER SIZE SCALE FACTOR

GKOP, WSOP, WSAC

CALL GQMKSC (ERRIND, MSZSF)

Output parameters:

ERRIND Error indicator IntegerMSZSF Marker size scale factor Real

Effect:


If the inquired information is not available, the marker size scale factor is returned as 0and the error indicator is set to one of the following error numbers to indicate the reasonfor non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE POLYMARKER COLOUR INDEX

GKOP, WSOP, WSAC

CALL GQPMCI (ERRIND, COLI)

Output parameters:

ERRIND Error indicator IntegerCOLI Polymarker colour index Integer


47 A2 40UL Rev01 5-51

Effect:


If the inquired information is not available, the colour index is returned as -1 and the errorindicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE TEXT FONT AND PRECISION

GKOP, WSOP, WSAC

CALL GQTXFP (ERRIND, FONT, PREC)

Output parameters:

ERRIND Error indicator IntegerFONT Text font IntegerPREC Text precision (GSTRP, GCHARP, Integer GSTRKP)

Effect:


If the inquired information is not available, the text font is returned as 0, text precision isreturned as -1 and the error indicator is set to one of the following error numbers toindicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.


5-52 47 A2 40UL Rev01

INQUIRE CHARACTER EXPANSION FACTOR

GKOP, WSOP, WSAC

CALL GQCHXP (ERRIND, CHXP)

Output parameters:

ERRIND Error indicator IntegerCHXP Character expansion factor Real

Effect:


If the inquired information is not available, character expansion factor is returned as 0and the error indicator is set to one of the following error numbers to indicate the reasonfor non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE CHARACTER SPACING GKOP, WSOP, WSAC

CALL GQCHSP (ERRIND, CHSP)

Output parameters:

ERRIND Error indicator IntegerCHSP Character spacing Real

Effect:

If the inquired information is available, the error indicator is returned as 0 and values arereturned in the Output parameters.


47 A2 40UL Rev01 5-53

If the inquired information is not available, character spacing is returned as 0 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE TEXT COLOUR INDEX GKOP, WSOP, WSAC

CALL GQTXCI (ERRIND, COLI)

Output parameters:

ERRIND Error indicator IntegerCOLI Text colour index Integer

Effect:


If the inquired information is not available, text colour index is returned as -1 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.


5-54 47 A2 40UL Rev01

INQUIRE CHARACTER SPACING GKOP, WSOP, WSAC

CALL GQCHSP (ERRIND, CHSP)

Output parameters:

ERRIND Error indicator IntegerCHSP Character spacing Real

Effect:


If the inquired information is not available, character spacing is returned as 0 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE TEXT COLOUR INDEX GKOP, WSOP, WSAC

CALL GQTXCI (ERRIND, COLI)

Output parameters:

ERRIND Error indicator IntegerCOLI Text colour index Integer

Effect:


If the inquired information is not available, text colour index is returned as -1 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:



47 A2 40UL Rev01 5-55

References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE FILL AREA INTERIOR STYLE

GKOP, WSOP, WSAC

CALL GQFAIS (ERRIND, INTS)

Output parameters:

ERRIND Error indicator IntegerINTS Fill area interior style Integer (GHOLLO, GSOLID, GPATTR, GHATCH)

Effect:


If the inquired information is not available, interior style -1 is returned and the errorindicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE FILL AREA STYLE INDEX GKOP, WSOP, WSAC

CALL GQFASI (ERRIND, STYLI)


5-56 47 A2 40UL Rev01

Output parameters:

ERRIND Error indicator IntegerSTYLI Fill area style index Integer

Effect:


If the inquired information is not available, fill area style index is returned as 0 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE FILL AREA COLOUR INDEX GKOP, WSOP, WSAC

CALL GQFACI (ERRIND, COLI)

Output parameters:

ERRIND Error indicator IntegerCOLI Fill area colour index Integer

Effect:


If the inquired information is not available, colour index is returned as -1 and the errorindicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3. 3. 3, 3. 6. 2.


47 A2 40UL Rev01 5-57

Errors:

none.

INQUIRE ASPECT SOURCE FLAGS GKOP, WSOP, WSAC

CALL GQASF (ERRIND, LASF)

Output parameters:

ERRIND Error indicator IntegerLASF (13) List of aspect source flags Integer (GBUNDL, GINDIV)

1. linetype ASF2. linewidth scale factor ASF3. polyline colour index ASF4. marker type ASF5. marker size scale factor ASF6. polymarker colour index ASF7. text font and precision ASF8. character expansion factor ASF9. character spacing ASF10. text colour index ASF11. fill area interior style ASF12. fill area style index ASF13. fill area colour index ASF

Effect:


If the inquired information is not available, the aspect source flags are returned as -1 andthe error indicator is set to one of the following error numbers to indicate the reason fornon-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.


5-58 47 A2 40UL Rev01

INQUIRE CURRENT NORMALIZATION TRANSFORMATION NUMBER

GKOP, WSOP, WSAC

CALL GQCNTN (ERRIND, CTNR)

Output parameters:

ERRIND Error indicator IntegerCTNR Current transformation number Integer

Effect:


If the inquired information is not available, current transformation number is returned as -1 and the error indicator is set to one of the following error numbers to indicate thereason for non-availability:


References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE LIST ELEMENT OF NORMALIZATION TRANSFORMATION NUMBERS

GKOP, WSOP, WSAC

CALL GQENTN (N, ERRIND, OL, NPRIO)

Input parameters:

N List element requested Integer

Output parameters:

ERRIND Error indicator IntegerOL Length of list IntegerNPRIO Nth element in list of Integer transformationnumbers


47 A2 40UL Rev01 5-59

Effect:


If the inquired information is not available, length of list is returned as 32, the element isreturned as 0 and the error indicator is set to one of the following error numbers toindicate the reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.902 List element or set member is not available.960 Number of arguments is invalid.

References:

3. 5. 1, 3. 6. 2.

Errors:

None.

INQUIRE NORMALIZATION TRANSFORMATION

GKOP, WSOP, WSAC

CALL GQNT (NTNR, ERRIND, WINDOW, VIEWPT)

Input parameters:

NTNR Normalization transformation Integer number

Output parameters:

ERRIND Error indicator IntegerWINDOW (4) Window limits in WC Real (WXMIN, WXMAX, WYMIN, WYMAX)VIEWPT (4) Viewport limits in NDC Real (VXMIN, VXMAX, VYMIN, VYMAX)

Effect:


If the inquired information is not available, all window and viewport limits are returned as0 and the error indicator is set to one of the following error numbers to indicate thereason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.50 Transformation number is invalid.960 Number of arguments is invalid.


5-60 47 A2 40UL Rev01

References:

3. 3. 3, 3. 6. 2.

Errors:

None.

INQUIRE CLIPPING INDICATOR GKOP, WSOP, WSAC

CALL GQCLIP (ERRIND, CLIP)

Output parameters:

ERRIND Error indicator Integer (GNCLIP, GCLIP)CLIP Clipping indicator Integer

Effect:


If the inquired information is not available, the clipping indicator is returned as -1 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3.3.3, 3.6.2.

Errors:

None.

5.6.5 Inquiry Functions for Workstation State List

INQUIRE WORKSTATION CONNECTION AND TYPE

WSOP, WSAC

CALL GQWKC (WKID, ERRIND, CONID, WTYPE)


47 A2 40UL Rev01 5-61

Input parameters:


Output parameters:

ERRIND Error indicator IntegerCONID Connection identifier IntegerWTYPE Workstation type Integer

Effect:


If the inquired information is not available, connection identifier is returned as 0,workstation type is returned as 0 in state GKCL and as the type of the workingworkstation in state GKOP, and the error indicator is set to one of the following errornumbers to indicate the reason for non-availability:


References:

3.4.2, 3.6.2.

Errors:

None.

INQUIRE WORKSTATION STATE WSOP, WSAC

CALL GQWKS (WKID, ERRIND, STATE)

Input parameters:


Output parameters:

ERRIND Error indicator IntegerSTATE Workstation state Integer (GINACT, GACTIV)

Effect:

If the inquired information is available, the error indicator is returned as 0 and valuesreturned in the output parameters.


5-62 47 A2 40UL Rev01

If the inquiered information is not available, the workstation state is returned as 0 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3.4.2, 3.6.2.

Errors:

None.

INQUIRE WORKSTATION DEFERRAL AND UPDATE STATES

WSOP, WSAC

CALL GQWKDU (WKID, ERRIND, DEFMOD, REGMOD, DEMPTY, NFRAME)

Input parameters:


Output parameters:

ERRIND Error indicator IntegerDEFMOD Deferral mode (GASAP, GBNIG, Integer GBNIL, GASTI)REGMODE Implicit regeneration mode Integer (GSUPPD, GALLOW)DEMPTY Display surface empty Integer (GNEMPT, GEMPTY)NFRAME New frame action necessary at Integer update (GNO, GYES)

Effect:

It the inquired information is available, the error indicator is returned as 0 and values arereturned in the output parameters.

If the inquired information is not available, all the parameters are returned as 0 exceptthe error indicator which is set to one of the following error numbers to indicate thereason for non-availability:



47 A2 40UL Rev01 5-63

Deferral mode controls the possible delaying of output functions. The values of deferralmode (in increasing order of delay) are:

ASAP The visual effect of each function will be acheived on theworkstation as soon as possible. This is the case for allsupported terminals.

BNIG the visual effect in this case will be acheived before the nextinteraction globally.

BNIL Before the next interaction locally.

ASTI At some time.

The implicit regeneration mode and the ``new frame action necessary at update`` aremeaningful only in the case of segments which are not supported. The value 0 isreturned.

The ``display surface empty`` flag indicates if the display surface is empty. Thischaracteristic is not supported and the value 0 is always returned.

Reference:

3.6.2.

Errors:

None.

INQUIRE TEXT EXTENT WSOP, WSAC


CALL GQTXX (WKID, PX, PY, STR, ERRIND, CPX, CPY, TXEXPX, TXEXPY)

Input parameters:

WKID Workstation identifier IntegerPX, PY Text position in WC RealSTR Character string Character*(*)

Output parameters:

ERRIND Error indicator IntegerCPX, CPY Concatenation point in WC RealTXEXPX (4) Text extent rectangle RealTXEXPY (4)

COBOL program only:

CALL ``GQTXXS' USING WKID, PX, PY, LG, STR, ERRIND, CPX, CPY,TXEXPX(1), TXEXPY(1).


5-64 47 A2 40UL Rev01

Input parameters:

77 WKID COMP-2. Workstation identifier77 PX COMP-9. Text position in WC77 PY COMP-9.77 LG COMP-2. Length of the string77 STR PIC X(n). Character string

Output parameters:

77 ERRIND COMP-2. Error indicator77 CPX COMP-9. Concatenation point in WC77 CPY COMP-9.01 TXEXX. Text extent rectangle 02 TXEXPX COMP-9. OCCURS 4.01 TXEXY. 02 TXEXPY COMP-9. OCCURS 4.

Effect:

If the inquiered information is available, the error indicator is returned as 0 and valuesare returned in the output parameters.

The extent of the specified character string is computed using the text font and precision,character expansion factor and character spacing currently selected (either via thebundle or individually, depending upon the corresponding ASFs) and the current textattributes (CHARACTER HEIGHT, CHARACTER UP VECTOR, TEXT PATH, TEXTALIGNMENT). If the current text index is not present in the text bundle table, text index 1is used.

At precisions STRING and CHAR, the text extent rectangle is an approximation of thatdefined in 3.3.6, being the minimum rectangle which ocmpletely encloses the characterbodies of the displayed string (see Figure 5-3). For UP and DOWN text paths, the widestcharacter body in the font is enclosed. The rectangle is returned as four corner points.

The concatenation point can be used as the origin of a subsequent TEXT outputprimitive for the concatenation of character strings, where appropriate. For certaincombinations of Text PATH and TEXT ALIGNMENT, concatenation is not appropriateand the returned concatenation point is the same as the text position.

If TEXT PATH is RIGHT or LEFT, the concatenation point is displaced from the textposition, in a direction determined by the horizontal component of TEXT ALIGNMENT. Ifthis component is LEFT, the direction is to the right; if it is CENTRE, the displacement iszero; if it is RIGHT, the direction is to the left.

If TEXT PATH is UP or DOWN, the concatenation point is displaced from the textposition in a direction determined by the vertical component of TEXT ALIGNMENT. Ifthis component is TOP or CAP, the direction is down; if it is HALF, the displacement iszero; if it is BASE or BOTTOM, the displacement is up.


6 GKS must be either in state WSOP or in state WSAC.25 Specified workstation is not open.101 Invalid code in string.960 Number of arguments is invalid.


47 A2 40UL Rev01 5-65

References:

3.3.6, 3.6.2, 4.5.4.

Errors:

None.

C H A R A C T E R S P A C I N G = 0CHARACTER UP VECTOR = (0 ,1 )TEXT PATH = R IGHTT E X T A L I G N M E N T = ( N O R M A L , N O R M A L )

C H A R A C TE R S PA C IN G = -0 .2C H A R A C TE R U P V EC T O R = (O ,1 )TE X T P A TH = LE FTTE X T A L IG N M E N T = (R IG H T .B A S E )

C H A R AC T E R S PA C IN G = 0 .2C H A R AC T E R U P V EC T O R = (0 ,1 )TE X T P A TH = D O W NTE X T A L IG N M E N T = (LE F T,T O P )

C H A R A C T E R SP A C IN G = 0C H A R A C T E R U P V E C T O R = (0 ,1 )T E X T P A T H = U PT E X T A L IG N M E N T =(C EN T R E ,B O T T T O M )

P:C:E1,E2,E3,E4:

tex t pos itionconcatenation po in tco rne rs o f tex t ex ten t rectang le , w h ichfo r T E XT P A T H = U P o r D O W N enc loses thew idest charac te r in the fron t

Figure 5-3. Examples of replies to INQUIRE TEXT EXTENTwith different text attributes


5-66 47 A2 40UL Rev01

INQUIRE LIST ELEMENT OF COLOUR INDICES

WSOP, WSAC

CALL GQECI (WKID, N, ERRIND, OL, COLIND)

Input parameters:

WKID Workstation identifier IntegerN List element requested Integer

Output parameters:

ERRIND Error indicator IntegerOL Number of colour table entries IntegerCOLIND Nth element of list of colour Integer indices

Effect:



6 GKS must be either in state WSOP or in state WSAC.25 Specified workstation is not open.902 List element or set member is not available.960 Number of arguments is invalid.

References:

3.3.10, 3.6.2.

Errors:

None.

INQUIRE COLOUR REPRESENTATION WSOP, WSAC

CALL GQCR (WKID, COLI, TYPE, ERRIND, RED, GREEN, BLUE)

Input parameters:

WKID Workstation identifier IntegerCOLI Colour index IntegerTYPE Item of returned values Integer (GSET, GREALI)


47 A2 40UL Rev01 5-67

Output parameters:

ERRIND Error indicator IntegerRED, GREEN, BLUE Colour (red/green/blue Real intensities)

Effect:


If the inquired information is not available, the intensities of colour are returned as 0 andthe error indicator is set to one of the following error numbers to indicate the reason fornon-availability:

6 GKS must be either in state WSOP or in state WSAC.25 Specified workstation is not open.87 Specified colour index not defined on this workstation.960 Number of arguments is invalid.

References:

3.3.10, 3.6.2.

Errors:

None.

INQUIRE WORKSTATION TRANSFORMATION WSOP, WSAC

CALL GQWKT (WKID, ERRIND, TUS, RWINDO, CWINDO, RVIEWP,CVIEWP)

Input parameters:


Output parameters:

ERRIND Error indicator IntegerTUS Workstation transformation Integer update state (GNPEND, GPEND)RWINDO(4) Requested workstation window Real in NDC (RWXMIN, RWXMAX, RWYMIN, RWYMAX)CWINDO(4) Current workstation window Real in NDC (CWXMIN, CWXMAX, CWYMIN, CWYMAX)RVIEWP(4) Requested workstation viewport Real in DC (RVXMIN, RVXMAX, RVYMIN, RVYMAX)CVIEWP(4) Current workstation viewport Real in DC (CVXMIN, CVXMAX, CVYMIN, CVYMAX)


5-68 47 A2 40UL Rev01

Effect:




References:

3.5.3, 3.6.2.

Errors:

None.

5.6.6 Inquiry Functions for Workstation Description Table

INQUIRE WORKSTATION CATEGORY GKOP, WSOP, WSAC

CALL GQWKCA (WTYPE, ERRIND, WKCAT)

Input parameters:

WTYPE Workstation type Integer

Output parameters:

ERRIND Error indicator IntegerWKCAT Workstation category Integer (GOUTPT, GINPUT, GOUTIN, GWISS, GMO, GMI)

Effect:


If the inquired information is not available, the workstation category is returned as -1 andthe error indicator is set to one of the following error numbers to indicate the reason fornon-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.23 Specified workstation type does not exist.960 Number of arguments is invalid.


47 A2 40UL Rev01 5-69

References:

3.4.1, 3.6.2.

Errors:

None.

INQUIRE WORKSTATION CLASSIFICATION

GKOP, WSOP, WSAC

CALL GQWKCL (WTYPE, ERRIND, VRTYPE)

Input parameters:


Output parameters:

ERRIND Error indicator IntegerVRTYPE Vector/raster/other type Integer (GVECTR, GRASTR, GOTHWK)

Effect:


If the inquired information is not available, the classification is returned as -1 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:


References:

3.4.1., 3.6.2.

Errors:

None.

INQUIRE MAXIMUM DISPLAY SURFACE SIZE

GKOP, WSOP, WSAC

CALL GQMDS (WTYPE, ERRIND, DCUNIT, RX, RY, LX, LY)


5-70 47 A2 40UL Rev01

Input parameters:


Output parameters:

ERRIND Error indicator IntegerDCUNIT Device coordinate units Integer (GMETRE, GOTHU)RX, RY Maximum display surface Real size (DC) RealLX, LY Maximum display surface size Integer (raster units)

Effect:


If the inquired information is not available, device coordinate units is returned as -1,maximum display surface size is returned as 0 and the error indicator is set to one of thefollowing error numbers to indicate the reason for non-availability:


References:

3.4.1, 3.6.2.

Errors:

None.

INQUIRE POLYLINE FACILITIES GKOP, WSOP, WSAC

CALL GQPLF (WTYPE, N, ERRIND, NLT, LT, NLW, NOMLW, RLWMIN,RLWMAX, NPPLI)

Input parameters:

WTYPE Workstation type IntegerN List element requested Integer


47 A2 40UL Rev01 5-71

Output parameters:

ERRIND Error indicator IntegerNLT Number of available linetypes IntegerLT Nth element in list of Integer available linetypesNLW Number of available linewidths IntegerNOMLW Nominal linewidth RealRLWMIN, RWLMAX Range of linewidths RealNPPLI Number of predefined polyline Integer indices

Effect:


If the inquired information is not available, all the output parameters are returned as 0except the error indicator, which is set to one of the following error numbers to indicatethe reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.23 Specified workstation type does not exist.902 List element or set member is not available.960 Number of arguments is invalid.

References:

3.4.1, 3.6.2

Errors:

None.

INQUIRE PREDEFINED POLYLINE REPRESENTATION

GKOP, WSOP, WSAC

CALL GQPPLR (WTYPE, PLI, ERRIND, LNTYPE, LWIDTH, COLI)

Input parameters:

WTYPE Workstation type IntegerPLI Predefined polyline index Integer

Output parameters:

ERRIND Error indicator IntegerLNTYPE Linetype IntegerLWIDTH Linewidth scale factor RealCOLI Polyline colour index Integer


5-72 47 A2 40UL Rev01

Effect:

If the inquired information is available, the error indicator is returned as 0 and values areretruned in the output parameters.

If the inquired information is not available, linetype and linewidth scale factor arereturned as 0, polyline colour index is returned as -1 and the error indicator is set to oneof the following error numbers to indicate the reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.23 Specified workstation type does not exist.60 Polyline index is invalid.960 Number of arguments is invalid.

References:

3.4.1, 3.6.2.

Errors:

None.

INQUIRE POLYMARKER FACILITIES GKOP, WSOP, WSAC

CALL GQPME (WTYPE, N, ERRIND, NMT, NMS, NOMMS, RMSMIN, RSMMAX, NPPMI)

Input parameters:


Output parameters:

ERRIND Error indicator IntegerNMT Number of available marker types IntegerMT Nth element in list of available Integer marker typesNMS Number of available marker sizes IntegerNOMMS Nominal marker size RealRMSMIN,RMSMAX Range of marker sizes RealNPPMI Number of predefined polymarker Integer indices

Effect:


If the inquired information is not available, all the output parameters are returned as 0except the error indicator which is set to one of the following error numbers to indicatethe reason for non-availability:


47 A2 40UL Rev01 5-73


References:

3.4.1, 3.6.2.

Errors:

None.

INQUIRE PREDEFINED POLYMARKER REPRESENTATION

GKOP, WSOP, WSAC

CALL GQPPMR (WTYPE, PMI, ERRIND, MKTYPE, MKSSCF, COLI)

Input parameters:

WTYPE Workstation type IntegerPMI Predefined polymarker index Integer

Output parameters:

ERRIND Error indicator IntegerMKTYPE Marker type IntegerMKSSCF Marker size scale factor RealCOLI Polymarker colour index Integer

Effect:


If the inquired information is not available, marker type and marker size scale factor arereturned as 0, polymarker colour index is returned as -1 and the error indicator is set toone of the following error numbers to indicate the reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.23 Specified workstation type does not exist.64 Polymarker index is invalid.960 Number of arguments is invalid.

References:

3.4.1, 3.6.2.

Errors:

None.


5-74 47 A2 40UL Rev01

INQUIRE TEXT FACILITIES GKOP, WSOP, WSAC

CALL GQTXF (WTYPE, N, ERRIND, NFPP, FONT, PREC, NCHH, MINCHH, MAXCHH, NCHX, MINCHX, MAXCHX,NPTXI)

Input parameters:


Output parameters:

ERRIND Error indicator IntegerNFPP Number of text font and Integer precision pairsFONT Nth element of list of text Integer fontsPREC Nth element of list of text Integer precisions (GSTRP, GCHARP, GSTRKP)NCHH Number of available character Integer heightsMINCHH Minimum character height (DC) RealMAXCHH Maximum character height (DC) RealNCHX Number of available character Integer expansion factorsMINCHX Minimum character expansion Real factorMAXCHX Maximum character expansion Real factorNPTXI Number of predefined text Integer indices

Effect:


It the inquired informaiton is not available, all the output parameters are returned as 0except the error indicator which is set to one of the following error numbers to indicatethe reason for non-availability:


References:

3.4.1, 3.6.2.

Errors:

None.


47 A2 40UL Rev01 5-75

INQUIRE PREDEFINED TEXT REPRESENTATION

GKOP, WSOP, WSAC

CALL GQPTXR (WTYPE, PTXI, ERRIND, FONT, FREC, CHARXP, CHARSP,COLI)

Input parameters:

WTYPE Workstation type IntegerPTXI Predefined text index Integer

Output parameters:

ERRIND Error indicator IntegerFONT Text font IntegerPREC Text precision (GSTRP, GCHARP, Integer GSTRKP)CHARXP Character expansion factor RealCHARSP Character spacing RealCOLI Text colour index Integer

Effect:

If the inquired information is available, the error indicator is returned as 0 and values arereturned in the output parameters. If the inquired information is not available, text font,character expansion factor and character spacing are returned as 0, text precision andtext colour index are returned as -1 and the error indicator is set to one of the followingerror numbers to indicate the reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.23 Specified workstation doez not exist.68 Text index is invalid.960 Number of arguments is invalid.

References:

3.4.1, 3.6.2.

Errors:

None.


5-76 47 A2 40UL Rev01

INQUIRE FILL AREA FACILITIES GKOP, WSOP, WSAC

CALL GQFAF (WTYPE, NI, NH, ERRIND, NIS, IS, NHS, HS, NPFAI)

Input parameters:

WTYPE Workstation type IntegerNI List element of IS requested IntegerNH List element of HS requested Integer

Output parameters:

ERRIND Error indicator IntegerNIS Number of available fill area Integer interior stylesIS NIth element in list of Integer available fill area interior styles (GHOLLO, GSOLID, GPATTR, GHATCH)NHS Number of available fill area Integer hatch stylesHS NHth element of list of Integer available fill area hatch style indicesNPFAI Number of predefined fill area Integer indices

Effect:


If the inquired information is not available, all the output parameters are returned as 0except the error indicator which is set to one of the following error numbers to indicatethe reason for non-availability:


References:

3.4.1, 3.6.2.

Errors:

None.

INQUIRE PREDEFINED FILL AREA REPRESENTATION

GKOP, WSOP, WSAC

CALL GQPFAR (WTYPE, PFAI, ERRIND, STYLE, STYLID, COLI)

Input parameters:

WTYPE Workstation type IntegerPFAI Predefined fill area index Integer


47 A2 40UL Rev01 5-77

Output parameters:

ERRIND Error indicator IntegerSTYLE Fill area interior style Integer (GHOLLO, GSOLID, GPATTR, GHATCH)STYLID Fill area style index IntegerCOLI Fill area colour index Integer

Effect:


If the inquired information is not available, fill area style index and fill area colour indexare returned as 0, fill area interior style is returned as -1 and the error indicator is set toone of the following error numbers to indicate the reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.23 Specified workstation type does not exist.75 Fill area index is invalid.960 Number of arguments is invalid.

References:

3.4.1, 3.6.2.

Errors:

None.

INQUIRE PATTERN FACILITIES GKOP, WSOP, WSAC

CALL GQPAF (WTYPE, ERRIND, NPPAI)

Input parameters:


Output parameters:

ERRIND Error indicator IntegerNPPAI Number of predefined pattern Integer indices

Effect:

It the inquired information is available, the error indicator is returned as 0 and values arereturned in the output parameters.

If the inquired information is not available, value 0 is returned and the error indicator isset to one of the following error numbers to indicate the reason for non-availability:



5-78 47 A2 40UL Rev01

References:

3.4.1, 3.6.2.

Errors:

None.

INQUIRE PREDEFINED PATTERN REPRESENTATION

GKOP, WSOP, WSAC

CALL GQPPAR (WTYPE, PPAI, NMX, MMY, ERRIND, N, M, PARRAY)

Input parameters:

WTYPE Workstation type IntegerPPAI Predefined pattern index IntegerNMX, MMY Maximum pattern array Integer dimensions

Output parameters:

ERRIND Error indicator IntegerN, M Pattern array dimensions used IntegerPARRAY (NMX, MMY) Pattern array Integer

Effect:


If the inquired information is not available, pattern array dimensions used and the firstelement of pattern array are returned as 0 and the error indicator is set to one of thefollowing error numbers to indicate the reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.23 Specified workstation type does not exist.83 Interior style PATTERN is not supported on this workstation.958 Pattern size and pattern reference point are not supported.960 Number of arguments is invalid.

References:

3.4.1, 3.6.2.

Errors:

None.


47 A2 40UL Rev01 5-79

INQUIRE COLOUR FACILITIES GKOP, WSOP, WSAC

CALL GQCF (WTYPE, ERRIND, NCOLI, COLA, NPCI)

Input parameters:


Output parameters:

ERRIND Error indicator IntegerNCOLI Number of colours IntegerCOLA Colour available (GMONOC, GCOLOR) IntegerNPCI Number of predefined colour Integer indices

Effect:


If the inquired information is not available, number of colours and number of predefinedcolour indices are returned as 0, colour available is returned as -1 and the error indicatoris set to one of the following error numbers to indicate the reason for non-availability:


References:

3.4.1, 3.6.2.

Errors:

None.

INQUIRE PREDEFINED COLOUR REPRESENTATION

GKOP, WSOP, WSAC

CALL GQPCR (WTYPE, PCI, ERRIND, RED, GREEN, BLUE)

Input parameters:

WTYPE Workstation type IntegerPCI Predefined colour index Integer


5-80 47 A2 40UL Rev01

Output parameters:

ERRIND Error indicator IntegerRED, GREEN, BLUE Colour (red/green/blue Real intensities)

Effect:


If the inquired information is not available, colour intensities are returned as 0 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.23 Specified workstation type does not exist.86 Colour index is invalid.954 This workstation does not support colour.960 Number of arguments is invalid.

References:

3.4.1, 3.6.2.

Errors:

None.

INQUiRE LIST ELEMENT OF AVAILABLE GDP

GKOP, WSOP, WSAC

CALL GQEGDP (WTYPE, N, ERRIND, NGDP, GDPL)

Input parameters:


Output parameters:

ERRIND Error indicator IntegerNGDP Number of available GDPS IntegerGDPL Nth element of list of GDP Integer identifiers

Effect:



47 A2 40UL Rev01 5-81

If the inquired information is not available, the output parameters are returned as 0except the error indicator which is set to one of the following error numbers to indicatethe reason for non-availability:


References:

3.4.1, 3.6.2.

Errors:

None.

INQUIRE GENERALIZED DRAWING PRIMITIVE

GKOP, WSOP, WSAC

CALL GQGDP (WTYPE, GDP, ERRIND, NBND, BNDL)

Input parameters:

WTYPE Workstation type IntegerGDP GDP identifier Integer

Output parameters:

ERRIND Error indicator IntegerNBND Number of sets of attributes Integer usedBNDL(4) List of sets of attributes Integer used (GPLBND, GPMBND, GTXBND, GFABND)

Effect:


If the inquired information is not available, number of sets of attributes used is returnedas 0, the first element of the list is returned as -1 and the error indicator is set to one ofthe following error numbers to indicate the reason for non-availability:

8 GKS must be in one of the states GKOP, WSOP, WSAC.23 Specified workstation type does not exist.41 Specified workstation type is not able to generate this GDP.960 Number of arguments is invalid.

References:

3.4.1, 3.6.2.

Errors:

None.


5-82 47 A2 40UL Rev01

5.6.7 Pixel Inquiries

INQUIRE PIXEL ARRAY DIMENSION WSOP, WSAC

CALL GQPXAD (WKID, PX, PY, QX, QY, ERRIND, N, M)

Input parameters:

WKID Workstation identifier IntegerPX, PY, QX, QY Two points in WC Real

Output parameters:

ERRIND Error indicator IntegerN,M Dimensions of pixel array Integer

Effect:


The points P. Q define a rectangle. By transformation P and Q by the currentnormalization and workstation transformations, the rectangle is mapped onton thedisplay surface. The number of columns and the number of rows of pixels, whosepositions lie within the rectangle, are returned. For this calculation no clipping is applied.

If the inquired information is not available, dimensions of pixel array are returned as 0and the error indicator is set to one of the following error numbers to indicate the reasonfor non-availability:

6 GKS must be either in state WSOP or in state WSAC.25 Specified workstadition is not open.960 Number of arguments in invalid.

References:

3.6.2.

Errors:

None.


47 A2 40UL Rev01 5-83

INQUIRE PIXEL ARRAY WSOP, WSAC

CALL GQPXA (WKID, PX, PY, DIMX, DIMY, NCS, NRS, DX, DY, ERRIND,INVVAL, COLIA)

Input parameters:

WKID Workstation identifier IntegerPX, PY Upper right corner (WC) RealDIMX, DIMY Dimensions of colour index Integer arrayNCS, NRS Starting column and starting Integer rowDX, DY Size of requested pixel array Integer part

Output parameters:

ERRIND Error indicator IntegerINVVAL Presence of invalid values Integer (GABSNT, GPRSNT)COLIA(DIMX, DIMY) Colour index array Integer

Effect:


If the inquired information is not available, INVVAL is returned as 0, the frist element ofcolour index array is returned as 0 and the error indicator is set to one of the followingerror numbers to indicate the reason for non-availability:

6 GKS must be either in state WSOP or in state WSAC.40 Specified workstation has no pixel readback capability.960 Number of arguments is invalid.

Note hat the three types of workstation have no pixel readback capability.

References:

3.6.2.

Errors:

None.


5-84 47 A2 40UL Rev01

INQUIRE PIXEL WSOP, WSAC

CALL GQPX (WKID, PX, PY, ERRIND, COLI)

Input parameters:

WKID Workstation identifier IntegerPX, PY Point in WC Real

Output parameters:

ERRIND Error indicator IntegerCOLI Colour index Integer

Effect:


By transforming P by the current normalization and workstation transformations, it ismapped onto a pixel of the display surface. The colour index is returned as 0 and theerror indicator is set to one of the following error numbers to indicate the reason for non-availability:

6 GKS must be either in state WSOP or in state WSAC.40 Specified workstation has no pixel readback capabilities.

References:

3.6.2.

Errors:

None.


47 A2 40UL Rev01 5-85

5.7 ERROR HANDLING

EMERGENCY CLOSE GKS GKCL, GKOP, WSOP, WSAC

CALL GECLKS

Parameters:

None.

Effect:

GKS is emergency closed (see 3.7). The following actions are performed (if possible):

• deactivate workstation,• close workstation,• close GKS.

If GKS is already closed, no action is taken.

References:

3.7

Errors:

none.

ERROR LOGGING GKCL, GKOP, WSOP, WSAC


CALL GERLOG (ERRNR, FCTID, ERRFIL)

Input parameters:

ERRNR Error number IntegerFCTID Function identification IntegerERRFIL Error file Integer

COBOL program only:

CALL ``GERLOGC`` USING ERRNR, FCTID [, ERRFIL].


5-86 47 A2 40UL Rev01

Input parameters:

77 ERRNR COMP-2. Error number77 FCTID COMP-2. Function identificationSELECT ERRFIL ASSIGN TO ifn WITH SSF. Error fileFD ERRFIL.

Effect:

The error logging procedure:

a) prints an error message and GKS function identification on the error file.

b) returns to the calling procedure.

Note that the last parameter has been defined in OPEN GKS. It can be omitted; ifomitted, error messages will be output on the terminal.

References:

3.7, 4.5.5, 4.5.7.2.

Errors:

None.

47 A2 40UL Rev01 6-1

6. GKS Data Structures

6.1 NOTATION AND DATA TYPES

The contents of the GKS data structures are listed in this section.

The information for each entry includes:

• the name of the entry• the permitted values• the data type• the initial value (if appropriate)

The notation used to express the data type, coordinate system and permitted values isalso used to describe the parameters of the GKS functions in Section 3.3.

The data type can be a simple type, which is one of the following:

I integer: whole number

R real: floating point number

S string: number of characters and character sequence

P point: two real values specifying the x- and y-coordinates of a locationin WC, NDC or DC space.

N name: Identification of a file or a procedure. This type is mapped ontointegers in FORTRAN and COBOL.

E enumeration type: A data type comparing a set of values. The set is defined byenumerating the identifiers which denote the values. This type ismapped onto integers in FORTRAN and COBOL.

Alternativel, the data type can be a combination of simple types:

• a vector of values, e.g. 2xR• a matrix of values, e.g. 2x3xR• a list of values of one type: the type can be a simple type or a vector, e.g. nxI or nx4xR• an array of values of simple type, e.g. nxnxI• an ordered pair of different types, e.g. (I,E).


6-2 47 A2 40UL Rev01

An occurence of n merely indicates a variable integer value and does not necessarilyrelate to other occurences of n.

For coordinate data, the relevant coordinate system is indicated:

WC - World Coordinate systemNDC - Normalized Device Coordinate system,DC - Device Coordinate system.

Permitted values can be specified by:

• a condition, e.g.>0 or [0,1], the latter implying that the value lies between 0 and 1inclusively

• a standard range of integer values, e.g. (1..4)

• a range of integer values in which the maximum is determined depending on theworkstation, for example (32..n). Note that an occurence of n does not necessarilyimply any relationship with other occurences of n; n merely denotes a variable integerin this context

• a list of values which constitute an enumeration type, e.g. (SUPPRESSED,ALLOWED)

• an ordered list of any of the above.

Initial values, if present, occur on the last column of the data structure lists. The followingabbreviations occur:

undef. - "undefined value"

i.d. - "implementation dependent" (depends on the workstation)

w.d.t. - initial value taken from the "workstation description table"

crt. - current

(BU, IN) - (BUNDLED, INDIVIDUAL)

(HO, S, P, HA) - (HOLLOW, SOLID, PATTERN, HATCH)

(R, L, U, D) - (RIGHT, LEFT, UP, DOWN)

STR - STRING

NOR - NORMAL

STK - STROKE

CH - CHAR

If no initial value is given, the value is set by the relevant GKS function.

GKS Data Structures

47 A2 40UL Rev01 6-3

6.2 OPERATING STATE

Operating state value (GKCL, GKOP, WSOP, WSAC) E GKCL(state variable)

6.3 GKS DESCRIPTION TABLE

Level of GKS (0a, 0b, 0c, 1a, 1b, 1c, 2a, 2b, 2c) E 0aNumber of available workstation types (1..n) I 3List of available workstation types nxN (1,2,3)Maximum normalization transformation number (1..n) I 32


6-4 47 A2 40UL Rev01

6.4 GKS STATE LIST

set of open workstations nxN emptyset of active workstations nxN emptycrt. polyline index (1..n) I 1crt. linetype (1..n) I 1crt. linewidth scale factor R i.d.crt. polyline colour index (0..n) I 1crt. linetype ASF (BU, IN) E bundledcrt. linewidth scale factor ASF (BU, IN) E bundledcrt. polyline colour index ASF (BU, IN) E bundledcrt. polymarker index (1..n) I 3crt. marker type (1..n) I 3crt. marker size scale factor R 1.0crt. polymarker colour index (0..n) I 1crt. marker type ASF (BU, IN) E bundledcrt. marker size scale factor ASF (BU, IN) E bundledcrt. polymarker colour index ASF (BU, IN) E bundledcrt. text index (1..n) I 1crt. text font and precision (1..n; STR, CH, STK) (I;E) 1; STRcrt. character expansion factor >0 R 1.0crt. character spacing R 0.0crt. text colour index (0..n) I 1crt. text font and precision ASF (BU, IN) E bundledcrt. character expansion factor ASF (BU, IN) E bundledcrt. character spacing ASF (BU, IN) E bundledcrt. text colour index ASF (BU, IN) E bundledcrt. character height WC> 0 R 0.01crt. character up vector WC 2xR (0,1)crt. text path (R,L,U,D) E RIGHTcrt. text alignment horizontal and vertical (NOR, LEFT, CENTRE, RIGHT; NOR, CAP, HALF, BASE, BOTTOM) xE (NOR, NOR)crt. fill area index (1..n) I 1crt. fill area interior style (HO, S, P, HA) E HOLLOWcrt. fill area index (1..n) I 1crt. fill area colour index (0..n) I 1crt. fill area interior style ASF (BU, IN) E bundledcrt. fill area style index ASF (BU, IN) E bundledcrt. fill area colour index ASF (BU, IN) E bundledcrt. pattern size WC SX.SY>0 2xR 0.0crt. pattern reference point WC P (0,0)crt. normalization transformation no(0..n) I 0

list of normalization transfrmations for every entry: normalization transformation no. (0..n) I entry no. window WC 4xR 0.1.0.1 viewport NDC 4xR 0.1.0.1 clipping indicator (CLIP, NOCLIP) E CLIP

GKS Data Structures

47 A2 40UL Rev01 6-5

6.5 WORKSTATION STATE LIST

One workstation state list exists for every open workstation.The first three of the following entries are initialized by OPEN WORKSTATION.

Workstation identifier NConnection identifier NWorkstation type NWorkstation state ( ACTIVE, INACTIVE) E INACTIVEDeferral mode (ASAP, BNIG, BNIL, ASTI) E ASAPImplicit regeneration mode (SUPPRESSED, ALLOWED) E SUPPRESSEDDisplay surface empty (EMPTY, NOTEMPTY) E EMPTYNew frame action necessary (NO, YES) E NO

Polyline bundle table entries (5..n) I w.d.t. for every entry: polyline index (1..n) I w.d.t. linetype (1..n) I w.d.t. linewth scale factor R w.d.t. polyline colour index (0..n) I w.d.t.

Polymarker bundle table entries (5..n) I w.d.t. for every entry: polymarker index (1..n) I w.d.t. marker type (1..n) I w.d.t. marker size scale factor R w.d.t. polymarker colour index (0..n) I w.d.t.

Text bundle table entries (2..n) I w.d.t. for every entry: text index (1..n) I w.d.t. text font and precision (1..n; STR, CH, STK) (I; E) w.d.t. character expansion factor > 0 R w.d.t. character spacing R w.d.t. text colour index (0..n) I w.d.t.

Number of fill area bundle table entries (5..n) I w.d.t. for every entry: fill area index (1..a) I w.d.t. fill area interior style (HO, S, P, HA) E w.d.t. fill area style index (1..a) I w.d.t. fill area colour index (0..n) I w.d.t.

Number of coulour table entries (2..n) I w.d.t. for every entry: colour index (0..n) I w.d.t. colour (red, green, blue intensities [0.1] 3xR w.d.t.

Workstation transformation update state (NOTPENDING, PENDING) E NOTPENDINGRequested workstation window NDC 4xR 0.1.0.1Crt. workstation viewport NDC 4xR 0.1.0.1Requested workstation viewport DC 4xR maximum display surface from w.d.t.Crt. workstation viewport DC 4xR maximum display surface from w.d.t.


6-6 47 A2 40UL Rev01

6.6 WORKSTATION DESCRIPTION TABLE

The workstation description tables cannot be changed by the application program. Thereis only one workstation description table for each workstation type.

Workstation type N i.d.Workstation category (OUTPUT, INPUT, OUTIN, WISS, MO, MI) E i.d.Device coordinate units (METRES, OTHER) E i.d.Maximum display surface size i.d. in device coordinate units DC > 0 2xR i.d. in raster units (integer by integer) 2xI i.d. (with vector displays, for example, the raster units give thehighest possible resolution: for raster number of columns andlines of the raster array)

Raster or vector display (VECTOR, RASTER, OTHER) E i.d. (VECTOR = vector display, RASTER = raster device and OTHER =other device, e.g. vector + raster)

Workstation transformation (IRG, IMM) E i.d. IRG = implicit regeneration necessary (may be deferred) IMM = performed immediately default values for: deferral mode (ASAP, BNIG, BNIL, ASTI) E i.d. implicit regeneration mode (SUPPRESSED, ALLOWED) E i.d.

Number of available linetypes (4..n) I i.d. list of available linetypes (1..n) nxI i.d.

Number of available linewidths (0..n) I i.d. (a value of 0 indicates that a continuous range of linewidths is supported) nominal linewidth DC >0 R i.d. minimum linewidth DC >0 R i.d. maximum linewidth DC >0 R i.d.

Number of predefined polyline indices (bundles) (5..n) I i.d. for every table entry: linetype (1..n) I i.d. linewidth scale factor R i.d. polyline colour index (within range of predefined colour indices) (0..n) I i.d.

Number of available marker types (5..n) I i.d. list of available marker types (1..n) nxI i.d.

Number of available marker sizes (0..n) I i.d. (a value of 0 indicates that a continuous range of marker sizes is supported) nominal marker size DC >0 R i.d. minimum marker size DC >0 R i.d. maximum marker size DC >0 R i.d.

GKS Data Structures

47 A2 40UL Rev01 6-7

Number of predefined polymarker indices (bundles) (5..n) I i.d. for every table entry: marker type (1..n) I i.d. marker size scale factor R i.d. polymarker colour index (within range of predefined colour indices) (0..n) I i.d.

Number of text font and precision pairs (1..n) I i.d. list of text font and precision pairs (1..n ; STRING, CHAR, STROKE) nx(I ; E) i.d.

Number of available character expansion factors (0..n) I i.d. (a value of 0 indicates that a continuous range of character expansion factors is supported) minimum character expansion factor >0 R i.d maximum character expansion factor >0 R i.d

Number of available character heights (0..n) I i.d. (a value of 0 indicates that a continuous range of character heights is supported) minimum character height DC >0 R i.d. maximum character height DC >0 R i.d.

Number of predefined text indices (bundles) (2..n) I i.d. for every table entry: text font and precision (1..n ; STR, CH, STR) (I ; E) i.d. character expansion factor >0 R i.d. character spacing R i.d. text colour index (within range of predefined colour indices) (0..n) I i.d.

Number of available fill area interior styles (1..4) I i.d. liste of available fill area interior styles (HO, S, P, HA) nxE i.d.

Number of available hatch styles (0..n) I i.d. list of available hatch styles (1..n) nxI i.d.

Number of predefined fill area indices (bundles) (5..n) I i.d. for every table entry: fill area interior style (HO, S, P, HA) E i.d. fill area style index (1..n) I i.d. (for interior style, PATTERN must be within range of predefined pattern indices or HATCH must be within range of available hatch styles) fill area colour index (within range of predefined colour indices) (1..n) I i.d.


6-8 47 A2 40UL Rev01

Number of available colours or intensities (0,2..n) I i.d. (a value of 0 indicates that a continuous range of colours is supported) colour available (COLOUR, MONOCHROME) E i.d.

Number of predefined colour indices (representations) (2..n) I i.d. for every table entry: colour (red, green, blue intensities) [0,1] 3xR i.d.

Number of available GDPs (0..n) I i.d. list of available GDPs (may be empty) for every GDP: GDP identifier N i.d.

Number of sets of attributes used (0..4) I i.d. list of sets of attributes used (POLYLINE, POLYMARKER, TEXT, FILL AREA) nxE i.d.

Maximum number of polyline bundle table entries (5..n) I i.d.Maximum number of polymarker bundle table entries (5..n) I i.d.Maximum number of text bundle table entries (2..n) I i.d.Maximum number of fill area bundle table entries (5..n) I i.d.Maximum number of colour indices (2..n) I i.d.

47 A2 40UL Rev01 7-1

7. GKS Metafile

7.1 INTRODUCTION

MTF is the GRP component which allows a user program to send and receive GKSgraphic data to and from indexed UFAS files.

In the GRP environment, these files are called ``graphic metafiles`` and are built fromlogical parts called ``pictures``. Each picture is composed of ``graphic items``, and eachitem corresponds to a GRP primitive executed by the user program.

A metafile to which data is being sent is called a ``metaout`` (MO).

A metafile from wich data is being retrieved is called a ``metain`` (MI). A file is thus in``MO mode`` if it is being written to, and in ``MI mode`` if it is being read.

Note that throughout this section:

• the `ùser prgram`` is the FORTRAN or COBOL code used to process a metafile

• where GCL is mentioned, you can assume that the equivalent JCL is also available

• where a primitive is mentioned by name (e.g. GOPWK) you can assume that itsequivalent for COBOL is also available with the same name plus an 's' (i.e.GOPWKS).


7-2 47 A2 40UL Rev01

7.2 PREPARATION AND ACTIVATION OF A METAFILE

Before a UFAS file can be accessed as a metafile, it must be:

1. Allocated (using GCL)

2. Assigned to the user program (either statically at program launching or dynamicallyat program run-time)

3. Assigned to a workstation (using the GOPWK primitive)

4. Activated (using the GACWK primitive)

Allocation

Use the GCL command BUILD FILE to allocate the UFAS file with the followingattributes (at least):

UFAS = INDEXEDRECSIZE = 270 to 1023KEYSIZE = 14KEYLOC = 1RECFORM = VCOLLATE = EBCDIC (default)

Program Assigning

The file can be assigned to your program either by the program itself at run-time or bythe ASGi parameter of the EXEC PG command launching the program.

In the latter case, set ASGi parameters so that:

• share of a metafile is NORMAL in IOF, or MONITOR in TDS• access of a MO is WRITE or SPWRITE in IOF, or SPWRITE in TDS• access of a MI is READ, SPREAD, WRITE or SPWRITE in IOF or TDS

In either case a FORTRAN program must include the OPEN statement. For example:

OPEN (UNIT = 1, FILE = 'MYEFN', STATUS = 'OLD')

UNIT must be specified, and must be an integer between 1 and 200 (inclusive) but notequal to 5, 6 or 7. The UNIT number is assigned to the file's EFN.

FILE is normally the file's EFN. It does not need to be specified if the file has beenassigned by ASGI at EXEC PG level, or if the program does not require exlusive accessto the file. On the other hand, fit it does require exclusive access, you can specify:

FILE = 'IFN = ifn'

Which assigns the file at program run-time with SHARE = NORMAL and ACCESS =SPWRITE, thus preventing other programs accessing the file. The ifn, incidentally, mustcorrespond to that specified by the FILEi parameter of the EXEC PG command.

GKS Metafile

47 A2 40UL Rev01 7-3

STATUS is not mandatory. However if at FORTRAN run-time the pre-allocated UFASfile is not recognised, the program will immediately terminate and, unless STATUS hasbeen specified, you will not be able to re-allocate this file at run-time.

Examples:

(1) GCL: EXEC_PG ABC FILE1 = 10 ASG1 = (MYEFN, READ, NORMAL)

FORTRAN: PROGRAM ABC OPEN (UNIT = 10, STATUS = 'OLD')

(2) GCL: EXEC_PG ABC

FORTRAN: PROGRAM ABC OPEN (UNIT = 10, FILE = 'MYEFN', STATUS = 'OLD')

(3) GCL: EXEC_PG ABC FILE1 = MYIFN ASG1 = (MYEFN, WRITE, NORMAL)

FORTRAN: PROGRAM ABC OPEN (UNIT = 10, FILE = 'IFN = MYIFN', STATUS = 'OLD')

(4) GCL: EXEC_PG ABC FILE1 = HCOBFOR1 ASG1= MYEFN

FORTRAN: PROGRAM ABC OPEN (UNIT = 10, FILE = 'IFN = HCOBFOR1', STATUS = 'OLD')

COBOL: SELECT MYCOBEFN ASSIGN TO HCOBFOR1

A COBOL program, whether IOF or TDS, must declare the file in the `ìnput-output``section and then open it using the OPEN INPUT statement.

For a TDS-controlled file with medium protection, processing with journal is required.


7-4 47 A2 40UL Rev01

Example:

GCL EXEC_PG Imname FILE1 = ifn ASG1 = (efn, READ, MONITOR) DEF1 = (JOURNAL = BEFORE)

COBOL: TDS-FILE-CONTROL SELECT MTF1 ASSIGN TO ifn ORGANIZATION INDEXED ACCESS MODE IS DYNAMIC (or RANDOM) RECORD KEY IS KEY1 . . . FD MTF1 LABEL RECORDS OMITTED DATA RECORD IS FILEREC1 01 FILEREC1 02 FILEKEY1 PIC X(14) 02 FILLER1 PIC X(n) (256 <= n <= 1009) . . INIT. OPEN INPUT MTF1 . .

Note that if the ACCESS MODE is declared SEQUENTIAL, the file will be rejected byMTF (but not in FORTRAN, where SEQUENTIAL is the default value).

Workstation Assigning

After a file has been assigned to a program, that program must then assign the file to aworkstation using the MTF primitive GOPWK.

GOPWK (WKID, CONID, WTYPE)

Parameters:

WKID Workstation identifier Input Integer (COMP-2)CONID Connection identifier Input Integer (COMP-2)WTYPE Workstation type Input Integer (COMP-2)

Effect:

CONID is the UNIT number in FORTRAN or the IFN pointer in COBOL (MTF1 in theprevious example).

Note that the GKS operating state indicates the state of the output driver. If GKS is in theoperating state GKOP, it remains in this state if the workstation opened is a MI.

WTYPE = 8, 9 or 10

GKS Metafile

47 A2 40UL Rev01 7-5

8 The file is used in MO mode and its previous contents are erased.

9 The file is used in MO mode and its previous contents are saved.

10 The file is used in MI mode.

When GOPWK is executed, MTF checks that:

• refmode is MOVE (FD default)• no CKPTLM has been defined (default)• access level of the file is LOGICAL (default)

If any of these is not the case, the workstation will not be assigned and an errormessage will be returned.

Errors:

8 GKS must be in one of the states GOPK, WSOP, WSAC.20 Specified workstation identifier is invalid.21 Specified connection identifier is invalid.22 Specified workstation type is invalid.703 Invalid file organization.704 UFAS file organization is not indexed.705 Wrong recform for the file.706 Wrong recsize for the UFAS file.708 Physical I/0 error.709 Wrong keysize for the UFAS file.710 Wrong keyloc for the UFAS file.713 Dummy allocation of the file.714 File is not open.715 File is not assigned.716 Access mode is PHYSICAL SEQUENCE or DIRECT BY ADDRESS.717 UFAS file does not have COLLATE = EBCDIC.718 No file opened on the FORTRAN unit.719 Maximum number of MI workstations is reached.720 Maximum number of workstations is reached.721 Share of the file is not convenient.722 Access of the file is not convenient.725 Specified metafile is not supported.727 Metafile is damaged.730 No free space in the metafile.732 File is already used with another identifier.734 Access level of the file is not LOGICAL.738 File exists. Output mode will erase it. (TDS)742 File is not correctly described.743 In COBOL, access mode of the file must be DIRECT.746 Remote files are not supported.747 Countlim must not be specified.748 File refmode is 'move' and not 'locate'.802 Error MTF: H_F7R_DPARA not located by DYNAD.808 Problem of data management.809 Error MTF: RFLDEF cannot find the file.811 Error MTF: problem with macro RTVLID.952 Only one output workstation can be opened.960 Number of arguments is invalid.


7-6 47 A2 40UL Rev01

Deassigning

When the user program has finished processing the file, it must

• deactivate the workstation using GDAWK• deassign the workstation using GCLWK• and, finally, close the file using the CLOSE statement

The CLOSE, statement must not be executed before GDAWK. If it is, GDAWK will failwith error 808, in which case the only proper way to close GRP is to execute theGECLKS primitive.

The primitives GDAWK, GCLWK and GECLKS were described in Section 5.

Summary

In FORTRAN, for example, a metafile may be opened, assigned, activated, deactivated,deassigned and closed as follows:

.

.OPEN (8, FILE = 'PCTL.UFAS', STATUS = 'OLD')CALL GOPWK (1, 8, 9)CALL GACWK (1)..CALL GDAWK (1)CALL GCLWK (1)CALL GCLKSCLOSE (8).

GKS Metafile

47 A2 40UL Rev01 7-7

7.3 PICTURE CONCEPTS

The maximum number of pictures allowed per metafile is 512, though you can extendthis limit using the pseudo-protection technique described in 7. 11.

Picture Naming

Each picture within the same metafile must have a unique name. A name must have nomore than 23 characters, and no more than 255 names (for a given metafile) can beginwith the same 7 characters.

Picture Opening

In order to access a picture, your program must first open that picture using the MGTprimitive GOPIC. This, along with all other MGT picture primitives, is described in 7. 4.

A picture is a ``MI picture`` if opened at a workstation which has been assigned to a MI,and a ``MO picture`` if the workstation has been assigned to a MO.

A MO picture can be read, written to, replaced or deleted. A MI picture can only read; itmust be re-opened as a MO picture if it is to be written to, replaced or deleted.

It is in fact possible to access a picture without first using GOPIC to open it. In MOmode, MTF looks for a current picture and, if it cannot find one, opens a default picturewith a name which is a concatenation of the username, date and time (the date and timebeing in the 11 character format yydddhhmmss). Then in MI mode, if no GOPIC isexecuted, the most recent default picture is selected and automatically opened. In bothMO and MI cases, you will receive a message notifying you of the default openings.

Picture State and Protection

To each picture is assigned a state:

• W for ``being written to``• R for ``readable``

and a protection:

• N for ``no protection`` (default)• W for ``write protection``, meaning only the creator or the System Administrator (SA)

can delete, replace or open it.• R for ``read protection``, meaning only the creator or SA can open and read it.

A MI picture always has state ``R``. It must be re-opened as a MO picture if state ``W`ìs required.


7-8 47 A2 40UL Rev01

When a MO picture is opened, its state is set to ``W``. While in this state it cannot beopened at any other workstation. Its state is reset to ``R`` when it is closed, i.e. when:

• another picture is opened (GOPIC)• the workstation is deactivated (GDAWK)• another workstation is activated (GACWK)• GECLKS is executed in normal conditions (in abnormal conditions, links with the file

are severed and its status cannot change)• there is user omission or break, or a system crash

The protection level of a picture can be changed only if the mode is MO and if the pictureis in state ``R`` (i.e. not open).

• protection ``W`` is assigned using GLOCKW• rotection ``R`` is assigned using GLOCKR• protection ``N`` is assigned using GNLOCK

The syntax of these primitives is given in 7.5.

GKS Metafile

47 A2 40UL Rev01 7-9

7.4 PICTURE MGT PRIMITIVES

GOPIC (WKID, PICNAME, REPLACE, FORCE)

Parameters:

WKID Workstation identifier Input IntegerPICNAME Name of the picture Input Char *(23)REPLACE 0 or 1 Input IntegerFORCE 0 or 1 Input Integer

Effect:

Opens a picture and assigns it to the workstation specified. (If a picture is already openat this workstation then that picture is automatically closed).

In MO mode, if the picture does not already exist, then a new one is created under thename specified and set to state ``W``.

If the picture does exist, its contents are erased unless one of the following conditionsare met:

• with protection ``N``, either replace = 0 and state = ``R`` or force = 0 and the requestoris the picture's creator or the SA.

• with protection ``R`` or ``W``, replace = 0 and the requestor is the picture's creator orthe SA.

• with protection ``X`` (an internal protection relating to the program interface), eitherreplace = 0 and state = ``R`` or force = 0 and the requestor is the picture's creator orthe SA.

In MI mode, the picture will be opened if it exists and not already open elsewhere (i.e.not in state ``W``). The parameters replace and force are ignored.

If GOPIC fails, the session is locked and subsequent MGT primitives will not beexecuted. This avoids an avalanche of unnecessary error messages. The lock remainsuntil a GUWK, GDAWK, GCLWK or another GOPIC is executed.


7-10 47 A2 40UL Rev01

Errors:

8 GKS must be in one of the states GOPK, WSOP, WSAC.25 Specified workstation is not open.30 Specified workstation is not active.708 Physical I/0 error.711 Specified workstation is not a metafile.712 In TDS, you may create 10 pictures at one go.727 Metafile is damaged.729 Directory of the metafile is full.737 Invalid arguments.749 Picture access is denied.750 Specified picture is in state W.751 Invalid length of picture name.752 Picture already exists; use replace parameter.753 Picture does not exist.808 Problem of data management960 Number of arguments is invalid.

GOPICS (WKID, LGNAME, PICNAME, REPLACE, FORCE)

Parameters:

WKID Workstation identifier Input COMP-2LGNAME Length of picture name Input COMP-2PICNAME Name of the picture Input PIC X(m)REPLACE 0 or 1 Input COMP-2FORCE 0 or 1 Input COMP-2

Effect:

As for GOPIC.

Errors:

As for GOPIC

GDLPIC (WKID, PICNAME, REPLACE, FORCE)

Parameters:

WKID Workstation identifier Input IntegerPICNAME Name of the picture Input Char *(23)REPLACE 0 or 1 Input IntegerFORCE 0 or 1 Input Integer

GKS Metafile

47 A2 40UL Rev01 7-11

Effect:

Deletes the specified picture if:

• it is a MO picture not currently open (i.e. in state ``R``)• in the case of protection ``N``, replace = 1 and force = 1• in the case of protection ``R`` or ``W``, the requestor is either the picture's creator or

the SA.

Errors:

3 GKS not in proper state: GKS must be in the state WSAC.25 Specified workstation is not open.30 Specified workstation is not active.32 Specified workstation is not of category MO.708 Physical I/0 error.711 Specified workstation is not a metafile.727 Metafile is damaged.737 Invalid arguments.749 Picture access is denied.751 Invalid length of picture name.752 Picture already exists; use replace parameter.753 Picture does not exist.808 Problem of data management960 Number of arguments is invalid.

GDLPICS (WKID, LGNAME, PICNAME, REPLACE, FORCE)

Parameters:

As for GOPICS.

Effect:

As for GDLPIC.

Errors:

As for GDLPIC

GLOCKW (WKID, PICNAME)

Parameters:

WKID Workstation identifier Input IntegerPICNAME Name of the picture Input Char *(23)


7-12 47 A2 40UL Rev01

Effect:

Converts the protection level of a picture to ``W`` if:

• it is a MO picture and in state ``R`` (i.e. not open)• the requestor is either the picture's creator or the SA

Errors:

3 GKS not in proper state: GKS must be in the state WSAC.25 Specified workstation is not open.30 Specified workstation is not active.32 Specified workstation is not of category MO.708 Physical I/0 error.711 Specified workstation is not a metafile.737 Invalid arguments.749 Picture access is denied.751 Invalid length of picture name.752 Picture already exists; use replace parameter.753 Picture does not exist.808 Problem of data management.960 Number of arguments is invalid.

GLOCKWS (WKID, LGNAME, PICNAME)

Parameters:

WKID Workstation identifier Input COMP-2LGNAME Length of picture name Input COMP-2PICNAME Name of picture Input PIC X(m)

Effect:

As for GLOCKW

Errors:

As for GLOCKW

GLOCKR (WKID, PICNAME)

Parameters:

As for GLOCKW.

Effect:

As for GLOCKW, except that the protection is set to ``R``.

GKS Metafile

47 A2 40UL Rev01 7-13

Errors:

As for GLOCKW.

GLOCKRS (WKID, LGNAME, PICNAME)

Parameters:

As for GLOCKWS

Effect:

As for GLOCKW, except that the protection is set to "R".

Errors:

As for GLOCKW

GNLOCK (WKID, PICNAME)

Parameters:

As for GLOCKW

Effect:

As for GLOCKW, except that the protection is set to "N".

Errors:

As for GLOCKW.

GNLOCKS (WKID, LGNAME, PICNAME)

Parameters:

As for GLOCKWS.

Effect:

As for GLOCKW, except that the protection is set to "N".


7-14 47 A2 40UL Rev01

Errors:

As for GLOCKW.

GQPIC (WKID, PICNAME, STATE, PROTECT, RETCODE)

Parameters:

WKID Workstation identifier Input IntegerPICNAME Name of the picture Input Char *(23)STATE State of picture Output IntegerPROTECT Protection level Output IntegerRETCODE Error return code Output Integer

Effect:

This returns to the user program the following information on the picture specified:

STATE 0 = picture does not exist in the metafile 1 = picture is in state ``R``-1 = picture is in state ``W`` 2 = error - see RETCODE parameter

PROTECT0 = no protection (``N``)1 = write protection (``W``)2 = read protection (``R``)

RETCODE0 = no error8 = GKS must be in one of the states GOPK, WSOP, SAC.25 = Specified workstation is not open30 = Specified workstation is not active711 = Specified workstation is not a metafile727 = Metafile is damaged737 = Invalid arguments751 = Invalid length of name of picture808 = Data management problem

Errors:

Note. Note that if there is an invalid number of arguments or if retcode is unsuitable,GQPIC is ignored and no error message is returned.

GQPICS (WKID, LGNAME, PICNAME, STATE, PROTECT, RETCODE)

GKS Metafile

47 A2 40UL Rev01 7-15

Parameters:

WKID Workstation identifier Input COMP-2LGNAME Length of picture name Input COMP-2PICNAME Name of the picture Input PIC X(m)STATE State of the picture Output COMP-2PROTECT Protection level Output COMP-2RETCODE Error return code Output COMP-2

Effect:

As for GQPIC.

Errors:

As for GQPIC.

GLSPIC (WKID, PICNAME)

Parameters:

WKID Workstation identifier Input IntegerPICNAME Name of the picture Input Char *(23)

Effect:

GLSPIC returns to the user terminal the following information about the specified picture:

• creator• state• protection• date and time of protection• number of bytes• number of items

This information can be listed for just one picture or, if you use the star convention, a setof pictures. If the star convention is used, you must specify a name part of at least 7characters before the star.

You must not use GLSPIC on a MI picture which is currently open.

Use GUWK to bring the MI session to an end, and then apply GLSPIC.

Note that nothing happens if the picture specified does not exist.


7-16 47 A2 40UL Rev01

Errors:

8 GKS must be in one of the states GOPK, WSOP, WSAC.25 Specified workstation is not open.30 Specified workstation is not active.708 Physical I/0 error.711 Specified workstation is not a metafile.727 Metafile is damaged.735 Primitive forbidden during picture reading.737 Invalid arguments.751 Invalid length of picture name.808 Problem of data management960 Number of arguments is invalid.

GLSPICS (WKID, LGNAME, PICNAME)

Parameters:

As for GLOCKWS.

Effect:

As for GLSPIC.

Errors:

As for GLSPIC.

GLSMTF (WKID, LIST) [FORTRAN or COBOL]

Parameters:

WKID Workstation identifier Input Integer (COMP-2)LIST 0 or 1 Input Integer (COMP-2)

Effect:

GLSMTF returns to the user terminal the following information on the specifiedworkstation (i.e. metafile):

• the MTF version (e.g. V3 or V4)• the number of pictures in the metafile

If list = 1 and the environment is IOF, the information as listed by GLSPIC is listed for allthe pictures (in alphabetical order) of the metafile. In TDS, only the version and numberpictures are listed.

Note that GLSTMF must not be used on a MI that is currently open.

Errors:

As for GLSPIC.

GKS Metafile

47 A2 40UL Rev01 7-17

7.5 GRAPHICAL ITEM CONCEPTS

A picture is composed of a sequence of up to 160 000 graphical items, each stored in ametafile record and corresponding to a GRP primitive.

Each file record is of type TLV, i.e. type-length-value. The interpretation of an itemnormally consists of three steps, and is performed by the user program calling thefollowing primitives:

1. GGTITM which returns the type and data length of the current graphical item of thecurrent assigned picture.

2. GRDITM which then moves the graphical data (the V of TLV) into the user area, i.e.an 80- character array in FORTRAN or a string in COBOL.

3. GIITM then inquirys MTF to interpret this data, i.e. to execute the correspondingGRP primitive and for example output a drawing to a peripheral (or to another file)or update a table for list for a function set.

To interpret the whole picture, the user program must contain these three primitivesinside a loop. This allows the user program to pick up, move and then interpret allgraphical items of a given type, or to skip over any item whose data size is too large forthe application's data structures.

As a general rule, the 'control' and 'inquiry' primitives are recognized (interpreted) withinwhatever environment is current, but the 'output' and 'set' primitives are recognized onlywithin the GRP environment.

In MO mode, the user program may write private items into the picture using the GWITMprimitive within the sequence of GRP primitives. This inputs the items's TLV to the fileand thus creates the corresponding item in the body of the picture.

Then is MI mode, the user program can closely supervize the pictures, parameterizetheir interpretation, label the drawings, etc.

On the other hand, if close supervision is not necessary you should use the non-standard primitive GITPIC (non-standard in the ISO GKS sense). This interprets thecurrent picture of a MI.

WARNING

Interpreting a picture may affect the tables or lists describing theGRP environment.

This can be avoided if you use the 'set' primitives carefully, or if youuse the primitive GRESET (see 7. 6).


7-18 47 A2 40UL Rev01

7.6 LIST OF GRAPHICAL ITEMS

Type Item Storage (bytes)1 GCLRWK 1111 GPL 16n + 7 (n = number of points)12 GPM 16n + 713 GTXT 27914 GFA 16n + 715 GCA 4xy + 4316 GGDP 16n + 9521 GSPLI 1122 GSLN 1123 GSLWSC 1125 GSPMI 1126 GSMK 1127 GSMKSC 1928 GSPMCI 1129 GSTXI 1130 GSTXFP 1931 GSCHXP 1132 GSCHSP 1133 GSTXCI 1134 GSCHUP 1935 GSTXP 1136 GSTXAL 1937 GSFAI 1138 GSFAIS 1139 GSPASI 1140 GSFACI 1143 GSASF 5556 GSCR 4361 GSWN 4362 GSVP 4363 GSELNT 1164 GSCLIP 1171 GSWKWN 4372 GSWKVP 4396 GSCHH 1197 GRESET 1199 EOP end of picture

GKS Metafile

47 A2 40UL Rev01 7-19

7.7 ITEM MGT PRIMITIVES

GWITM (WKID, TYPE, LITM, ITEM)

Parameters:

WKID Workstation identifier Input IntegerTYPE Item type Input IntegerLITM 1,..., n Input IntegerITEM Item (LITM) Input Char *(80)

Effect:

Writes the specified item to the specified MO (which must be active).

The type must be between 101 and 255 (inclusive).

The user area cannot be greater than 1024 bytes, which means that LITM must not begreater than 12.

If no picture is assigned, MTF opens a default one and sends a warning to the userterminal.

Errors:

3 GKS not in proper state: GKS must be in the state WSAC.25 Specified workstation is not open.30 Specified workstation is not active.32 Specified workstation is not of category MO.160 Item type is not allowed for user type.161 Item length is not valid.708 Physical I/0 error.721 In TDS, you may create 10 pictures at one go.727 Metafile is damaged.729 Directory of metafile is full.730 No disk space for the metafile.737 Invalid arguments.808 Problem of data management960 Number of arguments is invalid.

GWITMS (WKID, TYPE, MEASURE, ITEM)

Parameters:

WKID Workstation identifier Input COMP-2TYPE Item type Input COMP-2MEASURE User area in bytes Input COMP-2ITEM Item name Input PIC X(m)


7-20 47 A2 40UL Rev01

Effect:

As for GWITM.

Errors:

As for GWITM

GGTITM (WKID, TYPE, LENGTH)

Parameters:

WKID Workstation identifier Input Integer (COMP-2)TYPE Item type Output Integer (COMP-2)LENGTH Item length Output Integer (COMP-2)

Effect:

Returns to the user program the type and length of the current item. The next itembecomes the current one.

The MI specified must be active.

In FORTRAN, length specifies the dimension of the array used to move the graphicaldata. In COBOL, length is the number of bytes used to store this data.

If no picture is assigned, MTF looks for a default picture and sends a warning to the userterminal.

Errors:

8 GKS must be in one of the states GOPK, WSOP, WSAC.25 Specified workstation is not open.30 Specified workstation is not active.34 Specified workstation is not of category MI.162 No more MI data to read.708 Physical I/0 error.711 Specified workstation is not a metafile.736 No current picture assigned.737 Invalid arguments.750 Specified picture is in state W.960 Number of arguments is invalid.

GKS Metafile

47 A2 40UL Rev01 7-21

GRDITM (WKID, LMAX, LITM, ITEM)

Parameters:

WKID Workstation identifier Input IntegerLMAX Dimension of item data array Input IntegerLITM Actual length of item data Output IntegerITEM Item data array Output Char *(80)

Effect:

Transfers the item data to the user character array. The item concerned is either the lastitem treated by a GGTITM primitive or, if GGTITM has not been executed since pictureopening, the first item of the picture.

The LMAX is the dimension of array specified by the user, and the LITM returns theactual length of the data transferred to this array.

If LMAX = 0 no move is performed and no error signaled.

If LMAX < LITM then error 166 occurs.

If no picture is opened, MTF looks for a default one, tries to open it and treats the firstitem.

Errors:

As for GGTITM plus error 166.

166 Maximum item data record length is invalid.

GRDITMS (WKID, LMAX, LITM, ITEM)

Parameters:

As for GRDITM, except that LITM is in bytes and ITEM is a COBOL character variable.

Effect:

As for GRDITM.

Errors:

As for GRDITM.


7-22 47 A2 40UL Rev01

GIITM (TYPE, LITM, ITEM)

Parameters:

TYPE Item type Input IntegerLITM Dimension of item data array Input IntegerITEM Item data array Input Char *(80)

Effect:

The item data is interpreted on an activated output driver.

Errors:

3 GKS not in proper state: GKS must be in the state WSAC.161 Item length is invalid.164 Item type is not a valid GKS item.165 Content of item data record is invalid for the type.167 User item cannot be interpreted.737 Invalid arguments.960 Number of arguments is invalid.

GIITMS (TYPE, LITM, ITEM)

Parameters:

As for GIITM except that LITM is measured in bytes and item is a COBOL charactervariable.

Effect:

As for GIITM.

Errors:

As for GIITM.

GITPIC (WKID, RETCODE)

Parameters:

WKID Workstation identifie Input Integer (COMP-2)RETCODE Error return code Input Integer (COMP-2)

Effect:

This interprets the current picture of the specified metafile (which must be an active MI).

The operating state must be 3 (i.e WSAC).

GKS Metafile

47 A2 40UL Rev01 7-23

The picture must be in its initial state, i.e. just opened.

If no picture is opened, MTF looks for a default picture.

At the end of the interpretation, the picture remains open and is located at the last recordof the picture.

GITPIC has an advantage over GIITM in that it can skip over damaged records. Adamaged picture (missing records, non-MTF records present, etc.) cannot be correctlyinterpreted by the loop GGTIM-GRDITM-GIITM. But if GITPIC is used, at least the validparts will be interpreted.

If the environment is not suitable or if the picture is badly damaged, then one of thefollowing error codes will be returned by retcode: 0, 3, 34, 162, 735, 736, 705, or 808.See 7. 12.

Errors:

None.

GRESET ( )

Parameters:

None

Effect:

Resets the contents of tables assigned to the metafile to their initial value, i.e. to thatwhen the metafile was opened.

GRESET does not effect the list of workstations or the state of the driver.

Errors:

• possible errors from GUWK if the output driver is an MT281• 960 Number of arguments is invalid.


7-24 47 A2 40UL Rev01

7.8 SET AND INQUIRY PRIMITIVES

All 'set' primitives except GSCR can be recorded in a MO.

Note that recorded 'set' primitives will affect the lists or tables associated with the file;this is necessary in order to keep the environment logical for subsequent 'inquiry'primitives.

An 'inquiry' primitive can be recorded in a MO or MI, depending on whether it is specifiedwith the input parameter WKID, WTYPE or neither.

Those specified with neither can be recorded in a MI or MO.

Those specified with WTYPE cannot be recorded in either a MI or a MO, and attempts todo so will return the error.

702 Function forbidden with metafile.

Except for GQWKC, GQWKS and GQTXX, those primitives specified with WKID can berecorded in a MO but not in a MI. If WKID is a MI, the error returned will be.

700 Function forbidden with metafile input.

With GQWKC and GQWKS, WKID can be given as a MI or as a MO. GQTXX cannot berecorded in either a MI or a MO.

7.9 PROGRAMMING RULES IN TDS

There are 5 simple rules:

RULE 1: If a metafile is created to be used in MI mode, the file shouldbe declared with an input pmd in the TDS generation. Withan input-ouput pmd, the reading of the file will invoke GACand hence the locking of Ci.

RULE 2: Try to concentrate the processing of a picture in a singleCommitment Unit. This way you are sure nobody is deletingthe beginning of your picture while you are processing theend of it into another Commitment Unit.

RULE 3: Be very careful when using the force parameter of GOPIC. Ifforce = 0, you can be sure that you are not trespassing onanother user domain.

RULE 4: If a picture is especially big you may have to share theprocessing among several Commitment Units in order toavoid a lock list overflow by GAC.

RULE 5: In order to avoid concurrent access to the metafile, try toreserve a Commitment Unit for the following primitives:GOPWK, GDAWK, GECLKS, GLSMTF and GUWK.

This rule does not apply if the file is opened in input pmd.

GKS Metafile

47 A2 40UL Rev01 7-25

7.10 A SIMPLE EXAMPLE

Here is an easy FORTRAN program which builds a picture and then reads it on a T4105: DIMENSION ITEM (10) INTEGER ISTATE INTEGER IPROTECT INTEGER ILENGTH INTEGER ILEN CHARACTER *(80) ITEM CHARACTER *(23) PICNAME

CC Initiate the environment.C OPEN(3, FILE = 'PCTL. UFAS', STATUS: 'OLD') CALL GOPKS CALL GOPWK(1, 3, 9) CALL GACWK(1)CC Open a picture.C PICNAME = 'DRAWING' CALL GQPIC(1, PICNAME, ISTATE, IPROTECT) IF (ISTATE. EQ. 0) THEN CALL GOPIC(1, PICNAME, 0, 0) ENDIFCC Drawing.C . . .CC Set metafile in reading mode.C CALL GDAWK(1) CALL GCLWK(1) CALL GOPWK(1, 3, 10) CALL GACWK(1)CC TEKTRONIK device is opened.C CALL GOPWK(2, 0, 3) CALL GACWK(2)CC Read the picture.C CALL GOPIC(1, PICNAME, 0, 0)1 CALL GGTITM(1, ITYPE, ILENGTH) IF (ILENGTH. GT. 10) THEN GOTO 1 ENDIF IF (ITYPE. EQ. 99) THEN GOTO 2 ENDIF CALL GRDITM(1, ILENGTH, ILEN, ITEM) CALL GIITM(ITYPE, ILEN, ITEM) GOTO 1CC Close GKS.


7-26 47 A2 40UL Rev01

2 CALL GDAWK(2) CALL GCLWK(2) CALL GDAWK(1) CALL GCLWK(1) CALL GCLKS CLOSE(3) STOP END

Question 1: What happens if another user is writing to the picture?What if the picture 'DRAWING' already exists and is in state"W"?

Question 2: What can be done if the body of the picture is found to bedamaged during picture reading, i.e. if there is no end-of-picturerecord in the file??

Question 3: What happens when there is a polyline with 50 points in thedrawing?

Question 4: What single statement can replace the 3 lines from "1 CALLGGTITM" to "GOTO 1"?

Answer 1: If another user is writing to the picture, the FORTRAN program isaborted when it attempts to open the file. If the picture alreadyexists, then the GOPIC will not be performed and, at the firstdrawing statement, a default picture will be opened. If theprogram attempts to open the file as a MI, the GOPIC will fail, thefile will be locked and nothing will be performed.

Answer 2: Hope that it never happens! The program will go into a loopunless you add an increment for closer supervision.

Answer 3: This requires 11 items of 80 bytes each, which is more than the807 bytes allowed; hence the record will be skipped at reading.

Answer 4: "CALL GITPIC(1, IERROR)"

GKS Metafile

47 A2 40UL Rev01 7-27

7.11 NUMBER OF PICTURES

This subsection explains the relation between the number of pictures, n, as listed byGLSMTF and the number of pictures that actually exist. It is a somewhat technicalsection and can be skipped at first reading.

If a picture is in state "R" and then opened by a user program, it is temporarily assigneda protection "X". When the picture is closed, this protection resets to "N". However whilethe picture is open (with state "W"), the protection listed by GLSMTF will be "X", but thatlisted by the MGT primitive GLSPIC will be "N".

A picture is defined as "accessible" if its state is "R" or if its state is "W" with "X"protection. MTF recognizes only the accessible pictures of a metafile and so the numberof pictures to MTF (i.e. as listed by GLSMTF) is in fact the sum of accessible pictures,rather than the sum of all pictures.

A MO session is defined as the period between a GOPWK or GUWK and a GDAWK (orGELKS). At the beginning of a session, var(n) = 0, i.e. the number of pictures has notvaried. During a session, pictures may be created, replaced or deleted. This affectsvar(n) as follows:

Creating a picture: - var(n) = var(n) + 1

Deleting a picture: - var(n) = var(n) - 1 if picture is accessiblevar(n) = var(n) otherwise

Replacing a picture: - var(n) = var(n) if picture is accessiblevar(n) = var(n) + 1 otherwise

This gives, at the end of the session, a number n = var(n)+n which is updated in thedirectory of the metafile.

Each time var(n) is incremented, MTF checks that n+var(n) is less than or equal to 512.

Thus is IOF, which implies exlusive use of the file, the real number of pictures cannotexceed 512. However, in TDS, if 10 users each create 5 pictures (at the same time andin one session only) in a metafile that already has 500 pictures, then that file will have550 pictures. Thus the real limit to the number of pictures actually depends the availablespace of the file.

Nevertheless, to avoid the problem of limits in TDS, the user is not allowed to increasethe number of pictures by more than 10 in one session (i.e. var(n) cannot exceed 10).

WARNING

If due to user omission, break or system crash the user programterminates before the end of a session, it could happen that var(n) isnot 0 at the time of the termination. If this does happen, the file willnext be opened with the wrong number of accessible picturesrecorded in its directory. The user will not be aware of this until aGLSTMF is executed in IOF mode, which automatically corrects thedirectory where necessary.


7-28 47 A2 40UL Rev01

47 A2 40UL Rev01 8-1

8. GKS on the Bull PRT 1220

8.1 INTRODUCTION

This section contains information for using GKS with a BULL PRT 1220. It describes onlythe terminal-dependent features of the PRT 1220, which corresponds to workstation typenumber 4, thus completing the list of available workstation types as follows:

1 - ANDERSON JACOBSON 8322 - ANDERSON JACOBSON 8333 - TEKTRONIX 41054 - BULL PRT 1220

The PRT 1220 includes a graphic character set and, because there is only forwardpaper-feed, a bit map. The bit map is discussed in 8.2.

Each output primitive has attributes which control the appearance of parts of the picture.Some of these attributes are workstation dependent, and are described in 8.3.

All non-geometrical aspects of an output primitive can be controlled using:

• either several attributes,

• or just a single attribute with an index to a workstation dependent list (i.e. a bundletable). A bundle table exists for output primitives POLYLINE, POLYMARKER, FILLAREA and TEXT. The PRT 1220 bundle tables are given in 8.4.

For each GKS primitives, there are certain errors which can occur in relation to the PRT1220, and which do not cause the ERROR HANDLING procedure to be called. Theseare listed in 8.5.


8-2 47 A2 40UL Rev01

8.2 THE BIT MAP

Characteristics

When opening a PRT 1220, a bit map of 600*600 pixels is generated. The step betweentwo adjoining pixels is 1/60 inch on the X-axis and 1/ 72 inch on the Y-axis, which givesthe size of the bit map as 25.4* 21.2 in centimeters

The device coordinates are expressed in centimeters and lie within the range [ 0,25.4 ] *[ 0,21.2 ]. The origin is at the bottom left corner.

Access

The bit map is available as soon as the workstation is activated. It contains all the outputprimitives, without, at this point, displaying their visual effects.

The bit map is printed (on the PRT 1220) when the workstation is updated or when it isdeactivated. It is cleared (without being printed) when the workstation is cleared.

Special Features with TDS

Under TDS, bit maps are represented in an indexed UFAS file created and declared atTDS generation. This file will contain all the bit maps of the TDS users working with GKSon PRT 1220. A bit map is composed from 50 records of 912 bytes. The file's ifn namemust be GKSMAP and it must be created with the following parameters:

UFAS = INDEXEDRECSIZE = 912KEYLOC = 1KEYSIZE = 12

You are also advised to set CISIZE = 18240.

The UFAS file GKSMA must be declared in the TDS generation program.The following statements are mandatory:

• in the FILE CONTROL:

SELECT EXTERNAL GKSMAP ASSIGN TO efn ORGANIZATION INDEXED ACCESS DYNAMIC RECORD KEY IS KEYBLOC FILE STATUS IS BITMAP-STAT.

• in the TDS-FILE-DEFINITION:

FD GKSMAP LABEL RECORD OMITTED DATA RECORD IS BLOCKLINE. 01 BLOCKLINE PIC X(912).

GKS on the Bull PRT 1220

47 A2 40UL Rev01 8-3

• in the PROCESSING- CONTROL:

PROCESSING-MODE OF GKSMAP IS INPUT-OUTPUT. FILE-INTEGRITY GKSMAP MEDIUM.

• in the WORKING-STORAGE SECTION:

77 BITMAP-STAT PIC XX.

The UFAS file GKSMAP must be assigned with SHARE= MONITOR and ACCESS =SPWRITE, and defined with JOURNAL = BEFORE.


8-4 47 A2 40UL Rev01

8.3 OUTPUT PRIMITIVE ATTRIBUTES

The attributes determine the exact appearance of the output primitive. We present thecurrently available values of these attributes for each output primitive.

POLYMARKER Attributes

Polyline has 3 non-geometric attributes: linetypes, linewidth scale factor and polylinecolour index. The PRT 1220 supports 5 different linestyles:

----------- Linestyle 1 - - - - Linestyle 4

- - - - - - Linestyle 2 - - - - Linestyle 5

........... Linestyle 3

The width of the line is always the same and there is no colour.

POLYMARKER Attributes

POLYMARKER has 3 non-geometric attributes: marker type, marker size scale factorand colour index. The PRT 1220 supports 5 different marker types:

. . . Marker type 1 0 0 0 Marker type 4

+ + + Marker type 2 X X X Marker type 5

* * * Marker type 3

The marker size is always the same (nominal size of a character) and there is no colour.


47 A2 40UL Rev01 8-5

FILL AREA Attributes

FILL AREA has 3 non-geometric attributes: interior style, style index and fill area colourindex. The PRT 1220 supports 2 interior styles: HOLLOW and HATCH. The latterincludes boundaries. Figure 8-1 shows the 16 different HATCH styles available.

1 2 3 4

5 6 7 8

11 12 13 14

15 16 17 18

Figure 8-1. Hatch index for PRT 1220

TEXT Attributes

TEXT has 5 non-geometric attributes: text font, text precision, character expansionfactor, character spacing and text colour index. It has 4 geometric attributes: characterheight, character up vector, text path and text alignment.


8-6 47 A2 40UL Rev01

The PRT 1220 supports one font with precision STRING and CHAR and with only onecharacter expansion factor (1). In pixels, the font description is as follows:

11

9

center l ine

top (cap)

half l ine

base (bot tom

A

V

< >

In centimeters, this is a rectangular area of 0.38 * 0.39 cm.

All multiples of the basic character height are accepted ; they are converted to thenearest available character height.

Only one character up vector is supported: (0,1).

GDP Attributes

Generalized Drawing Primitives (GDP) have no explicit geometric attributes.Representation of the GDP at the workstation is controlled by zero, one or more sets ofPOLYLINE, POLYMARKER, FILL AREA and TEXT attributes, as follows:

box:axis:autoscale:chord, arc:pie, circle:

polyline set of attributespolyline set of attributesnonenone } The figure is always HOLLOW andnone } drawn with linestyle 1.


47 A2 40UL Rev01 8-7

8.4 BUNDLE TABLES

Using workstation-dependent bundle tables, a single attribute can be used to specify allthe non-geometric aspects of a primitive.

Polyline Bundle TableIndex Linestyle Linewidth Line colour

1 1 1 12 1 1 13 1 1 14 2 1 15 2 1 16 2 1 17 3 1 18 3 1 19 3 1 110 4 1 111 4 1 112 4 1 113 5 1 114 5 1 115 5 1 1


1 1 1 12 2 1 13 3 1 14 4 1 15 5 1 1


1 0 (hollow) 0 12 3 (hatch) 1 13 3 2 14 3 3 15 3 4 16 3 5 17 3 6 18 3 7 19 3 8 110 3 11 111 3 12 112 3 13 113 3 14 114 3 15 115 3 16 116 3 17 117 3 18 1


8-8 47 A2 40UL Rev01

Text Bundle TableIndex Font and

precisionExpansion factor Character

spacingColour

1 1, string 1 0 12 1, char 1 0 13 1, char 1 0.3125 14 1, char 1 -0.3125 1

8.5 ERROR LOGGING

There are 3 new error messages which can be returned:

966 File GKSMAP is not defined.967 Processing error in UFAS file.968 Error in terminal tables.

Error 966 will occur if GKSMAP is not defined correctly in a TDS environment.

Error 967 will occur during an I/0 operation on GKSMAP

Error 968 will occur if the terminal description is wrong.

If you define your OWN GERHND procedure, you must be careful with these errors. Theparameters of GERHND are usually:

ERR_CODE fixed bin (31) Number of the errorERR_FUNC fixed bin (31) Number of the functionNFICH fixed bin (31) Number of open file (for FORTRAN)

To pass the message as well as the return code, the address of the parameterERR_CODE must be declared as follows:

DCL 1 ERRORS, 2 CODE_ERR FIXED BIN (31), number of the error 2 A_ G4 CHAR (30) ; return code

47 A2 40UL Rev01 A-1

A. Function Lists

GKS function FORTRAN COBOL PAGE name name (if different)

Activate workstation GACWKCell array GCAClose GKS GCLKSClear workstation GCLRWKClose workstation GCLWKDeactivate workstation GDAWKEmergency close GKS GECLKSError logging GERLOG GERLOGCEscape GESCFill area GFAGeneralized Drawing Primitive GGDPGet Item Type From GKSM GGTITMInterpret Item GIITMOpen GKS GOPKS GOPKSCOpen workstation GOPWKPolyline GPLPolymarker GPMInquire Aspect Source Flags GQASFInquire colour facilities GQCFInquire character height GQCHHInquire character spacing GQCHSPInquire character up vector GQCHUPInquire character expansionfactor GQCHXPInquire clipping indicator GQCLIPInquire current normalizationtransformation number GQCNTNInquire colour representation GQCRInquire list element ofcolour indices GQECIInquire list element ofavailable GDP GQEGDPInquire list element ofnormalizationtransformation-numbers GQENTNInquire list element ofavailable workstation types GQEWKInquire fill area colourindex GQFACIInquire fill area facilities GQFAFInquire fill area index GQFAIInquire fill area interiorstyle GQFAISInquire fill area style index GQFASIInquire generalized drawingprimitive GQGDP


A-2 47 A2 40UL Rev01

Inquire linetype GQLNInquire level of GKS GQLVKSInquire linewidth scalefactor GQLWSCInquire maximum displaysurface size GQMDSInquire markertype GQMKInquire marker size scalefactor GQMKSCInquire maximum normalizationtransformation number GQMNTNInquire normalizationtransformation GQNTInquire operating state value GQOPSInquire set member of openworkstations GQOPWKInquire pattern size GQPAInquire pattern facilities GQPAFInquire pattern referencepoint GQPARFInquire predefined colourrepresentation GQPCRInquire predefined fill arearepresentation GQPFARInquire pick identifier GQPKIDInquire polyline colour index GQPLCIInquire polyline facilities GQPLFInquire polyline index GQPLIInquire polymarker colourindex GQPMCIInquire polymarker facilities GQPMFInquire polymarker index GQPMIInquire predefined patternrepresentation GQPPARInquire predefined polylinerepresentation GQPPLRInquire predefined polymarkerrepresentation GQPPMRInquire predefined textrepresentation GQPTXRInquire pixel GQPXInquire pixel array GQPXAInquire pixel arraydimensions GQPXADInquire text alignment GQTXALInquire text colour index GQTXCIInquire text facilities GQTXFInquire text font andprecision GQTXFPInquire text index GQTXIInquire text path GQTXPInquire text extent GQTXX GQTXXSInquire workstationconnection and type GQWKCInquire workstation category GQWKCAInquire workstationclassification GQWKCLInquire workstation deferraland update states GQWKDUInquire workstation state GQWKSInquire workstationtransformation GQWKTRead item from GKSM GRDITMSet aspect source flags GSASF

Function Lists

47 A2 40UL Rev01 A-3

Set character height GSCHHSet character spacing GSCHSPSet character up vector GSCHUPSet character expansionfactor GSCHXPSet clipping indicator GSCLIPSet colour representation GSCRSelect normalizationtransformation GSELNTSet fill area colour index GSFACISet fill area index GSFAISet fill area interior style GSFAISSet fill area style index GSFASISet linetype GSLNSet linewidth scale factor GSLWSCSet marker type GSMKSet marker size scale factor GSMKSCSet pattern size GSPASet pattern reference point GSPARFSet polyline colour index GSPLCISet polyline index GSPLISet polymarker colour index GSPMCISet polymarker index GSPMISet text alignment GSTXALSet text colour index GSTXCISet text font and precision GSTXFPSet text index GSTXISet text path GSTXPSet viewport GSVPSet workstation viewport GSWKVPSet workstation window GSWKWNSet window GSWNText GTX GTXSUpdate workstation GUWKWrite item to GKSM MGWITM


A-4 47 A2 40UL Rev01

47 A2 40UL Rev01 B-1

B. Error Lists

0 Internal error.1 GKS not in proper state : GKS must be in the state GKCL.2 GKS not in proper state : GKS must be in the state GKOP.3 GKS not in proper state : GKS must be in the state WSAC.6 GKS must be either in the state WSOP or in the state WSAC.8 GKS must be in one of the states GKOP, WSOP, WSAC.20 Specified workstation identifier is invalid.21 Specified connection identifier is invalid22 Specified workstation type is invalid.23 Specified workstation type does not exist.24 Specified workstation is open.25 Specified workstation is not open.26 Specified workstation cannot be opened.29 Specified workstation is active.30 Specified workstation is not active.31 Specified workstation is of category MO.32 Specified workstation is not of category MO.33 Specified workstation is of category MI.34 Specified workstation is not of category MI.39 Specified workstation is not of categories output, outin.40 Specified workstation has no pixel readback capability.41 Specified workstation type is not able to generate this GDP.50 Transformation number is invalid.51 Rectangle definition is invalid.52 Viewport is not within the NDC unit square.53 Workstation window is not within the ndc unit square.54 Workstation viewport is not within the display space.60 Polyline index is invalid.61 Specified polyline index not defined on this workstation.62 Linetype is less than or equal to zero.63 Specified linetype is not supported on this workstation.64 Polymarker index is invalid.65 Specified polymarker index not defined on this workstation.66 Marker type is less than or equal to zero.67 Specified marker type is not supported on this workstation.68 Text index is invalid.69 Specified text index not defined on this workstation.70 Text font is less than or equal to zero.71 Requested text font not supported for specified precision.72 Character expansion factor is less than or equal to zero.73 Character height is less than or equal to zero.74 Length of character up vector is zero.75 Fill area index is invalid.76 Specified fill area index not supported on this workstation.77 Fill area interior style not supported on this workstation.78 Style index is less than or equal to zero.


B-2 47 A2 40UL Rev01

79 Specified pattern index is invalid.80 Specified hatch style is not supported on this workstation.81 Pattern size value is not positive.82 Specified pattern index not defined on this workstation.83 Interior style pattern is not supported on this workstation.84 Dimensions of colour array are invalid.85 Colour index is less than zero.86 Colour index is invalid.87 Specified colour index not defined on this workstation.88 Colour is outside the range (0, 1).89 Pick identifier is invalid.100 Number of points is invalid.101 Invalid code in string.102 Generalized drawing primitive identifier is invalid.103 Content of GDP data record is invalid.104 At least 1 active workstation not able to generate this GDP.160 Item type is not allowed for user items.161 Item length is invalid.162 No record is left in GKS metafile input.163 Metafile item is invalid.164 Item type is not a valid GKS item.165 Data record and specified type are not compatible.166 Maximum item data record length is invalid.167 User item cannot be interpreted.180 Specified function is not supported.700 Function forbidden with metafile input.701 Forbidden inquire function in that context.702 Forbidden fuction with metafile.703 Invalid file organization.704 UFAS file does not have indexed organization.705 Wrong recform for the file.706 Wrong recsize for the file.707 UFAS file is not in SARF.708 Physical I/O error.709 Wrong keysize for the UFAS file.710 Wrong keyloc for the UFAS file.711 Specified workstation is not metafile.712 In TDS, you may create 10 pictures at one go.713 Dummy allocation of the file.714 File is not open.715 File is not assigned.716 Access mode is physical sequence or direct by address.717 UFAS file does not have COLLATE = EBCDIC.718 FORTRAN unit must be less than or equal to 200.719 Maximum number of MI workstations is reached.720 Maximum number of workstations is reached.721 Share of the file is not convenient.722 Access of the file is not convenient.723 Wrong processing mode for the file.724 Problem of right or access on file.725 Specified metafile is not supported.726 No file opened on the FORTRAN unit.727 Metafile is damaged.728 Directory of the metafile is damaged.729 Directory of the metafile is full.730 No free space in the metafile.731 Damaged record found in the metafile.732 File is already used with another identifier.733 Access mode of the file is not DIRECT.

Error Lists

47 A2 40UL Rev01 B-3

734 Access level of the file is not LOGICAL.735 Primitive forbidden during picture reading.736 No current picture assigned.737 Invalid arguments.738 File exists ; output mode will erase it.739 No more space for the picture.740 .741 MT281 with TW/TDS is not yet implemented.742 File is not well described.743 In COBOL, accmode of the UFAS file must be DIRECT.744 The picture cannot be opened.745 .746 Remote files are not supported.747 Countlim must not be specified.748 File refmode is locate and not move.749 Picture access is denied.750 Specified picture is in state W.751 Invalid length of name of picture.752 Picture already exists ; use replace parameter.753 Picture does not exit.800 Error MTF : problem with jobident or H_MT_TERMID.801 .802 Error MTF : H_F7R_DPARA not located by DYNAD.803 .804 Error MTF : problem during opening the file.805 .806 .807 .808 Problem of data management.809 Error MTF : RFLDEF cannot find the file.810 Error MTF : INTNBR not available.811 Error MTF : problem with macro RTVOLID.812 .849 Error MTF : internal problem.850 Error MTF : error code.950 Initialisation error.951 This workstation is not of the type requested.952 Only one output workstation can be open.953 Only one output workstation can be active.954 This workstation does not support colour.955 Lenght of the string is less than or equal to zero.956 Pick identifier is not supported.957 Member requested does not exist.958 Pattern size ans pattern reference point not supported.959 Metafile functions are not supported.902 List element or set member not available.960 Number of arguments is invalid.961 Error file is not opened.962 Error file is illegal.963 Formatted message-length is too small.964 Illegal floating point data.965 Connection identifier must be zero.966 File GKSMAP is not defined.967 Processing error in UFAS file.968 Error in terminal tables.


B-4 47 A2 40UL Rev01

47 A2 40UL Rev01 C-1

C. GKS Function Summary

C.1 CONTROL FUNCTIONS

OPEN GKSStart working with GKS

CLOSE GKSStop working with GKS

OPEN WORKSTATIONCreate a connection between a workstation and GKS

CLOSE WORKSTATIONRelease the connection between a workstation and GKS

ACTIVATE WORKSTATIONOutput is routed to this workstation from now on

DEACTIVATE WORKSTATIONOutput is no longer routed to this workstation

CLEAR WORKSTATIONPerform all deferred actions and clear display space on a workstation

UPDATE WORKSTATIONPerform all deferred actions and redisplay all visible segments stored on a workstation

ESCAPEA standard way of invoking non-standard features.


C-2 47 A2 40UL Rev01

C.2 OUTPUT FUNCTIONS

POLYLINEGenerate a polyline defined by points in WC

POLYMARKERGenerate markers of a given type at positions in WC

TEXTGenerate a text string at the given position in WC

FILL AREAGenerate a polygon which may be filled with a colour, a hatch or a pattern or may behollow.

CELL ARRAYMap the given array of colour indices onto the display surface

GENERALIZED DRAWING PRIMITIVEGenerate a generalized drawing primitive defined by a sequence of points in WC and adata record.

GKS Function Summary

47 A2 40UL Rev01 C-3

C.3 OUTPUT ATTRIBUTES

C.3.1 Workstation Independent Primitive Attributes

SET POLYLINE INDEXSelect a bundle index for polylines

SET LINETYPESet the linetype for use when the corresponding ASF is INDIVIDUAL

SET LINEWIDTH SCALE FACTORSet the linewidth scale factor for use when the corresponding ASF is INDIVIDUAL

SET POLYLINE COLOUR INDEXSet the polyline colour index for use when the corresponding ASF is INDIVIDUAL

SET POLYMARKER INDEXSelect a bundle index for polymarkers

SET MARKER TYPESet the marker type for use when the corresponding ASF is INDIVIDUAL

SET MARKER SIZE SCALE FACTORSet the marker size scale factor for use when the corresponding ASF is INDIVIDUAL

SET POLYMARKER COLOUR INDEXSet the polymarker colour index for use when the corresponding ASF is INDIVIDUAL

SET TEXT INDEXSelect a bundle index for text

SET TEXT FONT AND PRECISIONSet the text font and precision for use when the corresponding ASF is INDIVIDUAL

SET CHARACTER EXPANSION FACTORSet the character expansion factor for use when the corresponding ASF is INDIVIDUAL

SET CHARACTER SPACINGSet the character spacing for use when the corresponding ASF is INDIVIDUAL

SET TEXT COLOUR INDEXSet the text colour index for use when the corresponding ASF is INDIVIDUAL

SET CHARACTER HEIGHTSet the character height

SET CHARACTER UP VECTORSet the character up vector

SET TEXT PATHSelect the text path RIGHT, LEFT, UP or DOWN


C-4 47 A2 40UL Rev01

SET TEXT ALIGNMENTSet the horizontal and vertical alignment of character strings

SET FILL AREA INDEXSelect a bundle index for fill area primitives

SET FILL AREA INTERIOR STYLESet the fill area interior style for use when the corresponding ASF is INDIVIDUAL

SET FILL EREA STYLE INDEXSet the fill area style index for use when the corresponding ASF is INDIVIDUAL

SET FILL AREA COLOUR INDEXSet the fill area colour index for use when the coresponding ASF is INDIVIDUAL

SET PATTERN SIZESet the pattern size for use in the display of fill area primitive with interior style PATTERN

SET PATTERN REFERENCE POINTSet the pattern reference point for use in the display of fill area primitives with interiorstyle PATTERN

SET ASPECT SOURCE FLAGSDefine whether the value of each non-geometric aspect obtained from the correspondingindividual attribute or from the appropriate bundle on the workstation.

C.3.2 Workstation Attributes (representations)

SET COLOUR REPRESENTATIONDefine the colour to be associated with a colour index on a workstation

GKS Function Summary

47 A2 40UL Rev01 C-5

C.4 TRANSFORMATION FUNCTIONS

C.4.1 Normalization Transformation

SET WINDOWSet window in WC of a normalization transformation

SET VIEWPORTSet viewport in NDC of a normalization transformation

SELECT NORMALIZATION TRANSFORMATIONSelect normalization transformation for output

SET CLIPPING INDICATORSwitch clipping for normalization transformation off and on

C.4.2 Workstation Transformation

SET WORKSTATION WINDOWSet workstation window in NDC

SET WORKSTATION VIEWPORTSet workstation viewport in DC


C-6 47 A2 40UL Rev01

C.5 METAFILE FUNCTIONS

WRITE ITEM TO GKSMPass non-geographical data from the application program to the GKSM item

GET ITEM TYPE FROM GKSMPass the item type and item data record length of the currentGKSM item back to the application program.

READ ITEM FROM GKSMPass the current GKSM item to the application program(graphical or user item)

INTERPRET ITEMInterpret item read in by READ ITEM FROM GKSM. The interpretation causesappropriate changes in the set of GKS state variables and generates appropriategraphical output as determined by the metafile specification

C.6 INQUIRY FUNCTIONS

There are some 60 different inquiry functions defined in GKS. All variables contained inany existing state list and in the workstation description tables may be inquired at anytime when GKS is open.

An inquiry function is provided for text extent to allow concatenation of character strings.On raster workstation, the size and colour of pixel may be inquired.

The operating state of GKS may be inquired, even when GKS is closed.

C.7 ERROR HANDLING

EMERGENCY CLOSE GKSTries to close GKS in case of an error, saving as muchinformation as possible

ERROR HANDLINGA procedure called by GKS when an error is detected. It may be user supplied

ERROR LOGGINGA procedure called by the standard GKS error handling procedure. It prints an errormessage and function identification on the error file.

47 A2 40UL Rev01 D-1

D. Sample Programs

The following sample programs, based on the programming languages FORTRAN andCOBOL, illustrate the use of GKS functions.

Example 1:

This program generates rectangular fill area with the different attributes of fill area on aTEKTRONIX 4105.

PROGRAM PATTERN:

CC This program generates rectangular fill area withC different interior style.CC ASF bundle: Fill area index vary from 1 to 27.C ASF individual: Fill area interior style hollow.C Fill area interior style solid.C Fill area colour index vary from 0 to 8.C Fill area interior style hatch.C Fill area style index vary from 1 to 17.C Fill area interior style pattern.C Fill area style index vary from 50 to 174.C DIMENSION LASF (13)CC Initialisation.CC Open GKS.C CALL GOPKS (6)CC Open workstation type = TEKTRONIX 4105.C CALL GOPWK (1, 0, 3)CC Activate workstation.C CALL GACWK (1)CC Clear workstation.C CALL GCLRWK (1,0)CC BUNDLE TABLE FILL AREA ATTRIBUTES.


D-2 47 A2 40UL Rev01

C FILL AREA INDEX VARY FROM 1 TO 27.C XX=0.0 YY=0.0 INDEX=0 DO 200 I=1,3 DO 100 J=1,9 INDEX=INDEX+1 CALL GSFAI (INDEX) CALL REMPAR (XX,YY) XX=XX+0.11 100 CONTINUE XX=0.0 YY=YY+0.11

200 CONTINUEC MODIFICATION ASF INDIVIDUALC DO 300 I=1,13 LASF(I)=1 300 CONTINUE CALL GSASF (LASF(1))CC TEST CASE HOLLOWC CALL GSFAIS (0) CALL REMPAR (XX,YY)CC TEST SOLIDC CALL GSFAIS (1) INDEX=-1 DO 400 I=1,8 INDEX=INDEX+ XX=XX+0.11 CALL GSFACI (INDEX) CALL REMPAR (XX,YY) 400 CONTINUE XX=0.0 YY=YY+0.11 CALL GSFACI (8) CALL REMPAR (XX,YY)CC TEST HATCH INDEX FROM 1 TO 17C CALL GSFAIS (3) INDEX=0 DO 500 I=1,8 INDEX=INDEX+1 XX=XX+0.11 CALL GSFASI (INDEX) CALL REMPAR (XX,YY) 500 CONTINUE YY=YY+0.11 XX=0.0 DO 600 I=1,9 INDEX=INDEX+1 CALL GSFASI (INDEX) CALL REMPAR (XX,YY) XX=XX+0.11

Sample Programs

47 A2 40UL Rev01 D-3

600 CONTINUECC TEST PATTERN INDEX FROM 50 TO 174C CALL GSFAIS (2) YY=YY+0.11 XX=0.0 INDEX=49 DO 700 J=1,3 DO 650 I=1,9 INDEX=INDEX+1 CALL GSFASI (INDEX) CALL REMPAR (XX,YY) XX=XX+0.11 650 CONTINUE XX=0.0 YY=YY+0.11 700 CONTINUECC CALL A SUBROUTINE WHICH CLEARS THE DISPLAY SURFACEC CALL FENET XX=0.0 YY=0.0 DO 800 I=1,9 DO 750 J=1,9 INDEX=INDEX+1 CALL GSFASI (INDEX) CALL REMPAR (XX,YY) XX=XX+0.11 750 CONTINUE XX=XX+0.11 YY=YY+0.11 800 CONTINUECC CALL A SUBROUTINE WHICH CLEAR THE DISPLAY SURFACEC CALL FENET XX=0.0 YY=0.5 DO 900 J=1,2 DO 850 I=1,8 INDEX=INDEX+1 CALL GSFASI (INDEX) CALL REMPAR (XX,YY) XX=XX+0.11 850 CONTINUE XX=0.0 YY=YY+0.11 900 CONTINUECC DEACTIVATE WORKSTATION.CLOSE WORKSTATION.CLOSE GKSC CALL GECLKS STOP ENDCC SUBROUTINE FENET


D-4 47 A2 40UL Rev01

C CLEAR WORKSTATION IF CH1=CC SUBROUTINE FENET CHARACTER*1 CH1 50 WRITE (6,60) 60 FORMAT (1H,'TO CLEAR THE DISPLAY SPACE WRITE C:') READ (5,70) CH1 70 FORMAT (A1) IF (CH1.NE.'C') GO TO 50 CALL GCLRWK (1,0) RETURN ENDCC SUBROUTINE REMPARC GENERATES A RECTANGULAR FILL AREAC SUBROUTINE REMPAR (XX,YY) DIMENSION X(4),Y(4) XM=XX+0.1 YM=YY+0.1 X(1)=XX Y(1)=YY X(2)=XM Y(2)=YY X(3)=XM Y(3)=YM X(4)=XX Y(4)=YM CALL GFA (4,X(1),Y(1)) RETURN END

Example 2:

This program generates a pie divided in five parts given by the user on a TEKTRONIX4105.

PROGRAM PIE

C THIS PROGRAM GENERATES A PIE DIVIDED IN FIVE PARTS ON A TEK4105. THE PROGRAM ASKS THE USER THE PERCENTAGE OF FOUR PARTS ANDCALCULATE THE FIFTH PARTC X(4),Y(4) REAL A1,A2,A3,A4 CHARACTER*10 PRODCC INITIALISATIONCC OPEN GKSC CALL GOPKS(6)CC OPEN WORKSTATIONC CALL GOPWK(1,1,3)C

Sample Programs

47 A2 40UL Rev01 D-5

C ACTIVATE WORKSTATIONC CALL GACWK(1)CC SET WINDOW OF THE WORLD COORDINATES SPACEC CALL GSWN (1,-2.,2.,-2.,2.)CC SET NORMALIZATION TRANSFORMATIONC CALL GSELNT(1)CC SET WORKSTATION VIEWPORT (DEVICE COORDINATE SPACE)C CALL GSWKVP (1,480.,3612.,0.,3132.)CC TITLEC CALL GCLRWK (1,0)CC SET THE HIGHEST CHARACTER HEIGHTC CALL GSCHH (0.2) PROD='PRODUCTION'CC WRITE THE TITLEC CALL GTX (-0.9,-1.4,PROD) GO TO 150CC PARAMETERC 120 WRITE (6,140) 140 FORMAT (1H, 'THE ADDITION EXCEEDS 100') 150 WRITE (6,160) 160 FORMAT (1H,'PERCENTAGE (REAL) OF THE FOUR FIRST YEARS:') WRITE (6,180) 180 FORMAT (1H,' 1979 1980 1981 1982 ') READ (5,200)A1,A2,A3,A4 200 FORMAT (4F9.4)CC TEST TOTAL>100C QTOT=A1+A2+A3+A4 IF (QTOT.GT.100) GOTO 120 AUTRE=100.-QTOTCC 1ST QUARTERC TET1=6.28*A1/100. TET12=TET1/2 TET=TET1 X(1)=1.0 Y(1)=0.0 X(2)=COS(TET12) Y(2)=SIN(TET12) X(3)=COS(TET) Y(3)=SIN(TET)C


D-6 47 A2 40UL Rev01

C FILL AREA INDEX 4.INTERIOR STYLE SOLID.COLOUR GREENC CALL GSFAI (4)CC GDP NUMBER 6. PIEC CALL GGDP(3,X(1),Y(1),6,1,0)CC 2ND QUARTERC TET2=6.28*A2/100. TET22=TET+TET2/2 TET=TET+TET2 X(1)=X(3) Y(1)=Y(3) X(2)=COS(TET22) Y(2)=SIN(TET22) X(3)=COS(TET) Y(3)=SIN(TET)CC FILL AREA INDEX 3.INTERIOR STYLE SOLID.COLOR REDC CALL GSFAI (3) CALL GGDP(3,X(1),Y(1),6,1,0)CC 3RD QUARTERC TET3=6.28*A3/100. TET32=TET+TET3/2 TET=TET+TET3 X(1)=X(3) Y(1)=Y(3) X(2)=COS(TET32) Y(2)=SIN(TET32) X(3)=COS(TET) Y(3)=SIN(TET)CC FILL AREA INDEX 6.INTERIOR STYLE SOLID.COLOR CYANC CALL GSFAI (6) CALL GGDP(3,X(1),Y(1),6,1,0)CC 4TH QUARTERC TET4=6.28*A4/100. TET42=TET+TET4/2 TET=TET+TET4 X(1)=X(3) Y(1)=Y(3) X(2)=COS(TET42) Y(2)=SIN(TET42) X(3)=COS(TET) Y(3)=SIN(TET)C FILL AREA INDEX 8.INTERIOR STYLE SOLID.COLOR YELLOW CALL GSFAI (8) CALL GGDP(3,X(1),Y(1),6,1,0)C

Sample Programs

47 A2 40UL Rev01 D-7

C 5TH PARTC TET5=TET-6.28 TET52=TET5/2 X(1)=X(3) Y(1)=Y(3) X(2)=COS(TET52) Y(2)=SIN(TET52) X(3)=1.0 Y(3)=0.0CC FILL AREA INDEX 7.INTERIOR STYLE SOLID.COLOR MAGENTAC CALL GSFAI (7) CALL GGDP(3,X(1),Y(1),6,1,0)CC DEACTIVATE WORKSTATION.CLOSE WORKSTATION.CLOSE GKSC CALL GECLKS STOP END

Example 3:

The following program SQUARES gives an example of a program using GKS in COBOL.

In this program, error messages will be written on the error file ERRFIL. If this error file isthe member ERRORS of the library MLIBSL, the statement to execute it can be : EXECPG SQUARES LIB = MYLIBRARYLM FILE 1 = ERRFIL ASG1 = MLIBSL.. ERRORS

10 IDENTI2FICATION DIVISION.20 PROGRAM2-ID. SQUARES.25 *30 * This program draws internal squares with different solid40 * interior style.45 *50 AUTHOR. B DECROP.60 INSTALLATION. GAMBETTA.70 DATE-WRITTEN. AUGUST 1984.80 DATE-COMPILED.90 ENVIRONMENT DIVISION.100 CONFIGURATION SECTION.110 SOURCE-COMPUTER. HIS-SERIES-60 LEVEL-64.120 OBJECT-COMPUTER. HIS-SERIES-60 LEVEL-64.130 INPUT-OUTPUT SECTION.140 FILE-CONTROL.150 SELECT EXTERNAL ERRFIL ASSIGN TO ERRFIL WITH SSF.160 DATA DIVISION.170 FILE SECTION.180 FD ERRFIL LABEL RECORDS OMITTED.190 01 ERREUR PIC X(256).200 WORKING-STORAGE SECTION.210 01 X.220 02 XX COMP-9 OCCURS 6.230 01 Y.240 02 YY COMP-9 OCCURS 6.250 77 ERRIND COMP-2.260 77 WTYPE COMP-2.


D-8 47 A2 40UL Rev01

270 77 CONID COMP-2.280 77 INDICE COMP-2.290 77 I COMP-2.300 77 NB-POINT COMP-2310 77 VL1 COMP-2 VALUE 1.315 77 VLO COMP-2 VALUE 0.320 PROCEDURE DIVISION.330 *340 * Initialization and clear of the display surface350 *360 INITI.370 OPEN OUTPUT ERRFIL.375 *380 * Open GKS. Error messages written on file ERRFIL385 *390 CALL "GOPKSC'' USING ERRFIL.395 *400 * Ask the type of the terminal405 *410 CALL "GQWKC'' USING VL1, ERRIND, CONID, WTYPE.415 *420 * Open the workstation. Identifier is one. Type given bythe425 * last call.426 *430 CALL "GOPWK'' USING VL1, VLO, WTYPE.435 *440 * Activate workstation. Identifier 1.445 *450 CALL "GACWK'' USING VL1.455 *460 * Clear the display surface of workstation 1.465 *470 CALL "GCLARWK'' USING VL1, VL1.480 *490 * Test errors by calling OPEN GKS in state WSAC.500 * Error will be written on file ERRFIL510 *520 CALL "GOPKSC'' USING ERRFIL.530 *540 * Coordinates of the points of the first square550 *560 MOVE 0.8 TO XX(1).570 MOVE 0.8 TO YY(1).580 MOVE 0.2 TO XX(2).590 MOVE 0.8 TO YY(2).600 MOVE 0.2 TO XX(3).610 MOVE 0.2 TO YY(3).620 MOVE 0.8 TO XX(4).630 MOVE 0.2 TO YY(4).640 MOVE 3 TO INDICE. *650 * Set fill area index (bundle table) to interior655 * style solid.660 * Colour red. *

Sample Programs

47 A2 40UL Rev01 D-9

670 CALL "GSFAI'' USING INDICE.680 MOVE 4 TO NB-POINT.685 *690 Draw the first square695 *700 CALL "GFA'' USING NB-POINT, XX(1), YY(1).705 *710 * Draw the other squares715 *720 PERFORM NEXT-SQUARE VARYING I FROM 1 BY 1 UNTIL I = 80.725 *730 * Deactivate workstation. Close workstation. Close GKS.735 *740 CALL "GECLKS''.750 CLOSE ERRFIL.760 STOP RUN.770 *************************************************780 NEXT-SQUARE.790 ADD 1 TO INDICE.795 *800 * Fill area index 3 to 8 are interior style solid.810 * Colour Red. Green. Blue. Cyan. Magenta. Yellow.815 *820 IF INDICE = 9830 MOVE 3 TO INDICE.840 CALL "GSFAI'' USING INDICE.845 *850 * Compute the coordinates of the new square points.855 *860 SUBTRACT XX(2) FROM XX(1) GIVING XX(5).870 SUBTRACT YY(2) FROM YY(1) GIVING YY(5).880 SUBTRACT XX(3) FROM XX(2) GIVING XX(6).890 SUBTRACT YY(3) FROM YY(2) GIVING YY(6).900 DIVIDE XX(5) BY 20.0 GIVING XX(5).910 DIVIDE YY(5) BY 20.0 GIVING YY(5).920 DIVIDE XX(6) BY 20.0 GIVING XX(6).930 DIVIDE YY(6) BY 20.0 GIVING YY(6).940 SUBTRACT XX(5) FROM XX(1).950 SUBTRACT YY(5) FROM YY(1).960 SUBTRACT XX(6) FROM XX(2).970 SUBTRACT YY(6) FROM YY(2).980 ADD XX(5) TO XX(3).990 ADD YY(5) TO YY(3).1000 ADD XX(6) TO XX(4).1010 ADD YY(6) TO YY(4).1020 CALL "GFA'' USING NB-POINT, XX(1), YY(1).


D-10 47 A2 40UL Rev01

Technical publication remarks form

Title : DPS7000/XTA NOVASCALE 7000 GKS Reference Manual Languages: General

Reference Nº : 47 A2 40UL 01 Date: July 1987

ERRORS IN PUBLICATION

SUGGESTIONS FOR IMPROVEMENT TO PUBLICATION

Your comments will be promptly investigated by qualified technical personnel and action will be taken as required.If you require a written reply, please include your complete mailing address below.

NAME : Date :

COMPANY :

ADDRESS :

Please give this technical publication remarks form to your BULL representative or mail to:

Bull - Documentation Dept.

1 Rue de ProvenceBP 20838432 ECHIROLLES [email protected]

Technical publications ordering form

To order additional publications, please fill in a copy of this form and send it via mail to:

BULL CEDOC357 AVENUE PATTONB.P.2084549008 ANGERS CEDEX 01FRANCE

Phone: +33 (0) 2 41 73 72 66FAX: +33 (0) 2 41 73 70 66E-Mail: [email protected]

CEDOC Reference # Designation Qty

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

_ _ _ _ _ _ _ _ _ [ _ _ ]

[ _ _ ] : The latest revision will be provided if no revision number is given.

NAME: Date:

COMPANY:

ADDRESS:

PHONE: FAX:

E-MAIL:

For Bull Subsidiaries:

Identification:

For Bull Affiliated Customers:

Customer Code:

For Bull Internal Customers:

Budgetary Section:

For Others: Please ask your Bull representative.

BULL CEDOC

357 AVENUE PATTON

B.P.20845

49008 ANGERS CEDEX 01

FRANCE

47 A2 40UL 01REFERENCE

Documents

GKS Reference Manual - Atossupport.bull.com/ols/product/system/gcos7/gcos7... · GKS defines a language-independent nucleus of a graphic system. For integration into a programming