graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPINCH - Initialize Choice

GPINCH (wsid, device, choice, echo, area, datalen, data)

Purpose

Use GPINCH to specify initial values for a given choice device.

The Initialize Choice subroutine stores the initial choice number, prompt/echo type, echo area, and data record in the workstation state list for the specified device. For a keyboard choice device, an initial choice number less than 256 is interpreted using the workstation's input device character set. For details on the specific devices available on different workstation types, see The graPHIGS Programming Interface: Technical Reference or use the appropriate inquiry subroutines.

Note:

The choice device must be in Request mode.

Parameters

wsid -- specified by user, fullword integer

Workstation identifier.

device -- specified by user, fullword integer

Choice device number (>=1)

choice -- specified by user, fullword integer

Initial choice number (>=0)

echo -- specified by user, fullword integer

Prompt/echo type (>=1)

area -- specified by user, 6 short floating-point numbers (DC)

Echo area (Xmin, Xmax, Ymin, Ymax, Zmin, Zmax)

datalen -- specified by user, fullword integer

Data record length.

Note:

The data record length parameter must equal zero (datalen=0) if no data record is required for the given prompt/echo type. For prompt/echo types which require a data record, the specified data record length must be greater than, or equal to, 12.

data -- user specified, variable data

Choice data record.

Prompt/echo Types

Type One

designates the current choice number using a workstation-dependent technique.

Type Two

lets you indicate choice numbers by invoking the prompting capability.

Physical input devices commonly used as choice logical input devices have a built-in prompting capability. If the value of the i (th) element of the prompt array in the choice data record is 1=OFF , prompting of the i (th) alternative of the specified choice input device is turned off. An value of 2=ON indicates that prompting for that alternative is turned on. Choice echo Type Two requires the following data record:

                  ----------------------------
                0 |            n             |  number of integers
                  |--------------------------|
                4 |            0             |  number of reals
                  |--------------------------|
                8 |            0             |  number of strings
         -------- |--------------------------|
         |     12 |   prompt for choice 1    |
         |        |--------------------------|
    integers      /                          /
         |        /                          /
         |        |--------------------------|
         | n*4+12 |   prompt for choice n    |
         -------- ----------------------------

Prompt values are 1=OFF, 2=ON

Error Codes

25: SPECIFIED WORKSTATION DOES NOT EXIST
140: DEVICE NUMBER < ONE OR DEVICE NOT AVAILABLE
141: INPUT DEVICE NOT IN CORRECT MODE
144: PROMPT/ECHO TYPE NOT AVAILABLE ON WORKSTATION
145: ECHO AREA BOUNDARY VALUE IN ERROR
146: FIELD IN INPUT DEVICE DATA RECORD IN ERROR
152: INITIAL CHOICE VALUE < ZERO OR IS INVALID
324: PROMPT/ECHO TYPE < ONE
501: DATA RECORD WAS NOT SPECIFIED BUT IS REQUIRED
502: FIELD IN DATA RECORD NOT SUPPORTED ON WORKSTATION
509: DATA LENGTH VALUE < ZERO OR REQUIRED LENGTH

Related Subroutines

GPCHMO: Set Choice Mode
GPQCH: Inquire Choice Device State
GPQDCH: Inquire Default Choice Device Data
GPQDS: Inquire Maximum Display Surface Size
GPQLI: Inquire List of Logical Input Devices

RCP code

201335300 (X'0C002204')