INQUIRE CHOICE DEVICE STATE 3(3P) — Kubota Pacfic Computer Inc. (29 February 1991)

NAME

INQUIRE CHOICE DEVICE STATE 3 − inquire state of a choice device

SYNOPSIS

C Syntax

void
pinq_choice_st3 ( ws, dev, store, err, op_mode, echo_switch, init_status, init_choice,
prompt_echo, echo_vol, choice_data )
Pintws;workstation identifier
Pintdev;choice device number
Pstorestore;OUT pointer to buffer
Pint∗err;OUT error indicator
Pop_mode∗op_mode;OUT operating mode
Pecho_switch∗echo_switch;OUT echo switch
Pin_status∗init_status;OUT initial choice status
Pint∗init_choice;OUT initial choice
Pint∗prompt_echo;OUT prompt/echo type
Plimit3∗echo_vol;OUT echo volume
Pchoice_data3∗∗choice_data;OUT data record

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

Use INQUIRE CHOICE DEVICE STATE 3 to retrieve the current state of the specified choice device.

C Input Parameters

Applications using the C binding must create a buffer to be used by this function as memory space for storing data associated with the device state. This buffer is passed as the store argument.

The store buffer is a data area managed by the PHIGS. While the application is responsible for creating the initial buffer through a call to CREATE STORE, PHIGS manages this area such that there is sufficient memory for the specific inquiry. The choice device data record within the store buffer is accessed via the pointer pointed to by choice_data.

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

devThe device number of the choice device. See the Available Devices section of INITIALIZE CHOICE 3 for a description of the available devices.

storeThe memory buffer PHIGS is to use for storing the information returned. This buffer must exist prior to calling this function (see CREATE STORE (3P)).

errThe error indicator. See the Execution section below for a description of its use. See the Errors section below for the possible values it may return.

op_mode
A pointer to a variable of type Pop_mode, which will contain the current operating mode of the device. Pop_mode is enumerated in phigs.h as follows:

typedef enum {
POP_REQ,
POP_SAMPLE,
POP_EVENT
} Pop_mode;

echo_switch
A pointer to a variable of type Pecho_switch, which will contain the state of the device’s echo switch. The value returned for echo_switch will be either PSWITCH_ECHO or PSWITCH_NO_ECHO.

init_status
A pointer to a variable of type Pin_status, which contains the initial choice status of the device. Possible values for init_status are PIN_STATUS_OK and PIN_STATUS_NONE.

init_choice
A pointer to an integer that contains the value of the initial choice.

prompt_echo
A pointer to an integer that contains the value of the prompt/echo type.

echo_vol
A pointer to a Plimit3 structure defining the x, y, and z components of the echo volume, in Device Coordinates. Plimit3 is defined in phigs.h as follows:

typedef struct {
Pfloatx_min;/∗ minimum x coordinate value ∗/
Pfloatx_max;/∗ maximum x coordinate value ∗/
Pfloaty_min;/∗ minimum y coordinate value ∗/
Pfloaty_max;/∗ maximum y coordinate value ∗/
Pfloatz_min;/∗ minimum z coordinate value ∗/
Pfloatz_max;/∗ maximum z coordinate value ∗/
} Plimit3;

choice_data
A pointer to a Pchoice_data3 pointer. PHIGS assigns this pointer to the location in the Pstore structure that contains the device’s data record contents. Pchoice_data3 is defined in phigs.h as follows:

typedef struct {
union {
struct {
Pintunused;
} pet_r1;
struct {
Pintnum_prompts;/∗ number of alternatives ∗/
Ppr_switch∗prompts;/∗ array of prompts ∗/
} pet_r2;
struct {
Pintnum_strings;/∗ number of choice strings ∗/
char∗∗strings;/∗ array of choice strings ∗/
} pet_r3;
struct {
Pintnum_strings;/∗ number of alternatives ∗/
char∗∗strings;/∗ array of strings ∗/
} pet_r4;
struct {
Pintstruct_id;/∗ struct identifier ∗/
Pintnum_pick_ids;/∗ number of alternatives ∗/
Pint∗pick_ids;/∗ array of pick identifiers ∗/
} pet_r5;
} pets;
} Pchoice_data3;

Ppr_switch is an enumerated type with the following values:

typedef enum {
PPR_OFF,
PPR_ON
} Ppr_switch;

Execution

INQUIRE CHOICE DEVICE STATE 3 returns the current state of the specified choice device, which is stored in the workstation state list of the workstation associated with the device. The current state includes the operating mode, echo switch, initial choice, prompt/echo type, echo volume, and data record. See SET CHOICE MODE for a description of the operating mode and the echo switch, and how to set these values. See INITIALIZE CHOICE 3 for a description of the initial choice, prompt/echo type, echo volume, and data record contents, and how to set these values.

In the event of an error, the error indicator indicates the error number of the error detected, and no other output data is returned. If no error is detected, the error indicator is set to zero, and the inquired information will be available in the output parameters. Since this is an inquiry function, ERROR HANDLING is not invoked when an error is detected by this function.

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

Museum