NAME

REQUEST CHOICE − request an operator interaction with a choice device

SYNOPSIS

C Syntax

void
preq_choice ( ws, dev, in_status, choice )
Pintws;workstation identifier
Pintdev;choice device number
Pin_status∗in_status; OUT input status
Pint∗choice;OUT choice

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

Use REQUEST CHOICE to request an operator interaction with a specified choice device. The device must be in request mode. See SET CHOICE MODE and INITIALIZE CHOICE for more information. See the Available Devices section of INITIALIZE CHOICE for a description of the available choice devices. 

The request suspends PHIGS until the specified device is triggered, or the operator performs a BREAK.  A BREAK is performed by typing the CONTROL and D keys simultaneously (^D). 

C Input Parameters

wsWorkstation identifier. An integer specifying the workstation with which the requested choice device is associated. 

devThe device number of the requested choice device. 

C Output Parameters

in_status
A pointer to the location to store the status of the request. Pin_status is defined in phigs.h as follows:

typedef enum {
PIN_STATUS_NONE,
PIN_STATUS_OK,
PIN_STATUS_NO_IN
} Pin_status;

choiceA pointer to the location to store the selected choice value, if any. 

Execution

REQUEST CHOICE requests a logical input value from the specified choice device.  The specified device must be in request mode.  See SET CHOICE MODE for more information. 

REQUEST CHOICE creates a measure process for the specified device and suspends PHIGS until the device is triggered or the operator issues a BREAK.  A BREAK is generated by the operator by depressing the CONTROL and D keys simultaneously (^D). 

If the choice device is triggered and a choice has not been made, the status is returned as PIN_STATUS_NONE, and no choice value is returned. 

If the choice device is triggered and a choice has been made, the status is returned as PIN_STATUS_OK, and the choice value contains the choice number selected by the operator. 

If a BREAK occurs, the status is returned as PIN_STATUS_NO_IN, and no choice value is returned. 

In either case, when the device is triggered or a BREAK is issued, the current measure process is terminated and PHIGS processing resumes. 

ERRORS

003Ignoring function, function requires state (PHOP, WSOP, ∗, ∗)

054Ignoring function, the specified workstation is not open

061Ignoring function, specified workstation is neither of category INPUT nor of category OUTIN

250Ignoring function, the specified device is not available on the specified workstation

251Ignoring function, the function requires the input device to be in REQUEST mode

SEE ALSO

INITIALIZE CHOICE 3 (3P)
SET CHOICE MODE (3P)

September 02, 1992