Chapter 1. General Information for Workstations

This chapter contains two areas pertaining to all workstations supported by the graPHIGS API. The first section, Accessing a Workstation, describes the workstation types and how connection identifiers (CONNIDs : see CONNID [Connection Identifier]) are used by the graPHIGS API when opening a workstation. The second section, Description Tables in the graPHIGS API, provides lists of the initial default values in the graPHIGS API Traversal State List and view table entries in the Workstation View Table Data at initialization.

Accessing a Workstation

In order to display graphical data from an application program, the graPHIGS API requires information about the workstation. The graPHIGS API must know the capabilities and characteristics of the workstation as well as the information to access the workstation using the operating system. This information is identified to the graPHIGS API with the workstation type and connection identifier parameters of the Open Workstation (GPOPWS) and Create Workstation (GPCRWS) subroutines. (See The graPHIGS Programming Interface: Subroutine Reference .)

The final workstation type and connection identifier used by the graPHIGS API are the result of processing the nicknames in the External Defaults File (EDF) or the Application Defaults Interface Block (ADIB) and may differ from the parameters specified on GPOPWS and GPCRWS. See Chapter 7, Controlling the Environment with Defaults and Nicknames.

Workstation Types

Workstations of a certain class that share specific characteristics are referred to as a workstation type. For example, 5080 workstations are of the same type, although each may or may not have certain optional features (such as color capability). However, 5080 workstations are of a different workstation type than NATIVE workstations because of different capabilities.

The workstation category of the user's physical workstation is identified by the workstation type parameter on the Open Workstation (GPOPWS) or Create Workstation (GPCRWS) subroutine call.

The graPHIGS API supports the following workstation types:

When you specify the workstation type parameter on the GPOPWS or GPCRWS subroutine calls, the workstation type is passed as an 8-byte character string, left-justified with blanks padding on the right of the type (example, 'NATIVE ' ).

Refer to Chapter 3, Workstation Description Tables, for information about the supported workstation types.

For information about using nickname processing to pass workstation types to the graPHIGS API, see Chapter 7, Controlling the Environment with Defaults and Nicknames.

The data values of the Workstation Description Table (WDT) describe the capabilities and characteristics of a workstation type. The data values of the WDT are available to your application through the WDT group of inquiries (see The graPHIGS Programming Interface: Subroutine Reference ). The workstation type parameter of the WDT inquiries identifies the category of workstation whose data is requested. (The WDT group of inquiries return only data that does not change during the processing of your application. The WSL group of inquiries return the current state of workstation data values that your application can change.)

When either the Open Workstation (GPOPWS) or Create Workstation (GPCRWS) subroutine calls create a workstation resource, the graPHIGS API creates a new unique workstation type. This created ("realized") workstation type precisely describes the actual capabilities of the created workstation. For example, 5080 workstations may, in general, support the dial input devices. However, a particular 5080 may not have the dials present. The actual WDT will not have an entry for the valuator devices, where the general ("generic") WDT will have such an entry. The actual workstation type is available to your application using the Inquire Realized Workstation Category and Type (GPQRCT) subroutine. You can then use the returned realized workstation type as the wstype parameter on the WDT group of inquiries.

Connection Identifiers

The connection identifier specified on Open Workstation (GPOPWS) and Create Workstation (GPCRWS) subroutines is used by the graPHIGS API to access a specific device for processing. The identifier is passed to the operating system, typically for allocation of the workstation.

For the 6090 the connection identifier is an "*" (asterisk).

For the 5080 in the S/390 environment , the connection identifier must be the DDNAME (MVS) or FILEDEF name (VM) which defines the device you wish to access. On VM, for example, issue the following command prior to running your application:

    FILEDEF IBM5080 GRAF 120

For GDDM (*) supported devices the connection identifier is used as the "name-list" by the graPHIGS API when it issues the GDDM call DSOPEN. (See GDDM Base: Programming Reference for details of the DSOPEN call and the name-list parameter.) For example, specifying a connection identifier of "*" will indicate to GDDM (by passing a name-list of "*") that the user console is to be used as the workstation.

GDDM nickname processing may be performed on the data passed on the DSOPEN call (see GDDM Base: Programming Reference ). The DSOPEN call issued by the graPHIGS API takes the form:

DSOPEN (DEVID, FAM, DEVTOK, 0, 0, NAMEC, NAMEL)
         |      |     |             |      |
         |      |     |             |      name list, the first entry
         |      |     |             |          of which is set equal to
         |      |     |             |          the connection identifier
         |      |     |             name count and is always set to 1
         |      |     GDDM device token (always '*')
         |      GDDM family (always 1)
         [default] encoded device identifier

In the AIX(*) environment, the connection identifier defines the workstation you wish to access.

• The connection identifier for a NATIVE workstation is the device name for the workstation you are using. The device names are:

  'hft/n'	Lower case; causes graPHIGS API(*) to open /dev/hft/n
  '*'	Causes graPHIGS API to open /dev/hft (which will open dev/hft/n where n is the next available number)

• The connection identifier for an X workstation specifies which X server the graPHIGS API workstation window will be associated with.

  '*'	the graPHIGS API will connect to the server specified in the AIX environment DISPLAY variable.
  'host:serverscreen	This is a standard X server specification, where host is the host name where an X server is running, server is the server ID, and screen is the screen number.

For information about using nickname processing to pass connection identifiers to the graPHIGS API, see Chapter 7, Controlling the Environment with Defaults and Nicknames.

For further information about the connection identifier passed when generating GDF files, CGM files, or IMAGE files, see The GDF Workstation, The CGM Workstation, or The IMAGE Workstation.

Description Tables in the graPHIGS API

This section contains two tables:

• The graPHIGS API Traversal State List
• Workstation View Table Data

The data types of the returned values are identified by the following codes:

Note: The notation of n (number) [default] t (data type) indicates a collection of data of that type. This can be indicated in one of two ways:

1. by using notation such as 3[default]R (three real numbers), which could specify something like the x, y, and z coordinates of a three-dimensional point or RGB values
2. by using a variable number such as n[default]I, which specifies a collection of n integers.

The values identified with the symbol * reflect the default value of a workstation configuration variable; that is, this may not be the actual workstation value after the workstation is opened. (See The graPHIGS Programming Interface: Understanding Concepts for a discussion of workstations.)

The graPHIGS API Traversal State List

Table 1. The graPHIGS API Traversal Defaults Table

Workstation View Table Data

When a workstation is opened with Open Workstation (GPOPWS) or Create Workstation (GPCRWS), a Workstation State List (WSL) is created. The WSL is initialized from information in the actual Workstation Description Table (WDT) that is modified to reflect the capabilities of the specific workstation to be used. The workstation transformation values and the view table in the WSL are initialized to the following values. The right-hand column lists the appropriate inquiry subroutine and parameter.

Table 2. WSL View Parameters at Initialization