NAME

REQUEST STRING − request an operator interaction with a string device

SYNOPSIS

C Syntax

void
preq_string ( ws, dev, in_status, string )
Pintws;workstation identifier
Pintdev;string device number
Pin_status∗in_status;OUT input string
char∗string;OUT string

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

Use REQUEST STRING to request an operator interaction with a specified string device. The device must be in request mode. See SET STRING MODE and INITIALIZE STRING for more information.  See the Available Devices section of INITIALIZE STRING for a description of the available string 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 string device is associated. 

devThe device number of the requested string device.  See the Available Devices section of INITIALIZE STRING for a description of the available string devices. 

C Output Parameter

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;

stringA pointer to an array in which to store the string.  The array must be allocated by the caller and should be at least as large as the buffer size of the device. 

Execution

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

REQUEST STRING 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 a BREAK occurs, a status of PIN_STATUS_NO_IN is returned and the string data is undefined.  If a status of PIN_STATUS_OK is returned, the string data is available.  In either case, the measure process is terminated and PHIGS processing resumes. 

For a description of the available string devices, see INITIALIZE STRING. 

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 STRING (3P)
SET STRING MODE (3P)

September 02, 1992