graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPQPDC - Inquire Physical Device Characteristics

GPQPDC (wstype, category, device, number, errind, flags, type, totnum, vrange)

Note:

This subroutine is a Workstation Description Table (WDT) inquiry. For an overview, see "WDT Inquiries"

Purpose

Use GPQPDC to retrieve the characteristics of a physical input device for the specified workstation type.

If the information is available, then the graPHIGS API sets the error indicator to zero and returns the values in the output parameter. If the error indicator is 533 (an output parameter is not large enough for all the requested data), then the values up to the length specified are returned. If the inquired information is unavailable, then the error indicator (errind) contains the error number indicating the reason, and the values returned in the output parameter are unpredictable.

Parameters

wstype -- specified by user, 8-byte character string

Workstation type.

category -- specified by user, fullword integer

Physical device category (1=BUTTON, 2=SCALAR, 3=2D_VECTOR )

device -- specified by user, fullword integer

Physical device number (>=1)

number -- specified by user, fullword integer

Number of array entries for parameter vrange that have been provided by the application (>=0)

errind -- returned by the graPHIGS API, fullword integer

Error indicator. If the error indicator is zero, the request has been completed. Otherwise, one of the following errors exists:

23: SPECIFIED WORKSTATION TYPE DOES NOT EXIST
140: DEVICE NUMBER < ONE OR DEVICE NOT AVAILABLE
160: PHYSICAL INPUT DEVICE CATEGORY IS INVALID
533: INQUIRY DATA EXCEEDS AREA. OUTPUT TRUNCATED
539: REQUESTED NUMBER < ZERO
548: SPECIFIED WORKSTATION TYPE CANNOT BE LOADED

flags -- returned by the graPHIGS API, fullword integer

Indicates whether this device is actually present and if it may be emulated by the application (1=NOT_PRESENT_CANNOT_BE_EMULATED, 2=NOT_PRESENT_CAN_BE_EMULATED, 3=PRESENT_CANNOT_BE_EMULATED, 4=PRESENT_CAN_BE_EMULATED )

type -- returned by the graPHIGS API, fullword integer

Type of physical input device. The interpretation of this parameter is dependent on the category of input device as follows:

Button -: (1=KEYBOARD, 2=OTHER ) This field identifies whether the button device is a keyboard or not.
Scalar -: (1=ABSOLUTE, 2=RELATIVE ) This parameter indicates whether the physical input device generates relative or absolute values.
2D Vector -: (1=ABSOLUTE, 2=RELATIVE ) This parameter indicates whether the physical input device generates relative or absolute values.

totnum -- returned by the graPHIGS API, fullword integer

Total number of value ranges that describe the specified physical input device.

vrange -- returned by the graPHIGS API, array of fullword integers

The parameter contains a list of integer pairs that define value ranges for the specified physical device. The interpretation of these value ranges are dependent on the category of the physical input device as follows:

Button -

Each value range defines a series of button values that may be generated by the device.

Scalar -

There is only one range for this device in all cases.

If the physical device generates absolute values then this range defines the minimum and maximum value that may be generated. The minimum and maximum values generally correspond to the minimum and maximum range of the logical input device.

If the device generates relative values, then the minimum of this range is always zero and has no meaning. The maximum of the range represents the number of increments in one unit of physical motion. A unit of physical motion is different for different physical devices.

Note: For a dial physical device, one unit of physical motion equals one turn of the dial.

2D Vector -

There are two ranges for this device in all cases. The first corresponds to the x value that is generated and the second corresponds to the y value.

If the physical device generates absolute values, then this range defines the minimum and maximum value that may be generated. The minimum and maximum values generally correspond to the edges of the screen in the case of a device connected to the graphics cursor.

Note: For a mouse physical device, one unit of physical motion equals the amount of motion necessary to move the cursor from one edge of the screen to its opposite edge.

Error Codes

None

Related Subroutines

GPQRCT: Inquire Realized Connection Type

RCP code

201339409 (X'0C003211')