request_locator(3G)

NAME

request_locator, intrequest_locator2d − wait for input device to be triggered then return measured value

SYNOPSIS

C Syntax:

void request_locator(fildes,ordinal,timeout,valid,x,y,z);
int fildes,ordinal,*valid;
float timeout,*x,*y,*z;

void intrequest_locator2d(fildes,ordinal,timeout,valid,x,y);
int fildes,ordinal,*valid,*x,*y;
float timeout;

FORTRAN77 Syntax:

subroutine request_locator(fildes,ordinal,timeout,valid,x,y,z)
integer*4 fildes,ordinal,valid
real timeout,x,y,z

subroutine intrequest_locator2d(fildes,ordinal,timeout,valid,x,y)
integer*4 fildes,ordinal,valid,x,y
real timeout

Pascal Syntax:

procedure request_locator(fildes,ordinal:integer;timeout:real;
var valid:integer;var x,y,z:real);

procedure intrequest_locator2d(fildes,ordinal:integer;timeout:real;
var valid,x,y:integer);

DESCRIPTION

Input Parameters

fildes Integer file descriptor returned by gopen when an I/O path to a graphics device is opened.

ordinal Logical device number ranging from 1 to number of devices of this class.

timeout Time, in seconds, to wait for a trigger.

Output Parameters

valid TRUE (1 in Pascal) if data is valid.

FALSE (0 in Pascal) if data is invalid (timeout period exceeded or device not initialized). If FALSE, x,y,z is undefined.

x,y,z Set to x, y, and z virtual device coordinate values of the point returned from a locator device.

Discussion

Request_locator returns the measured value of the device specified by fildes and ordinal when a trigger occurs, or when the time period specified by timeout is exceeded. If the request was not previously posted with initiate_request and no request data is ready for this device, it is posted by this call. If a request was previously posted but not yet satisfied, the timeout runs from the time this call was made.

A request can be performed on an input device while it is enabled for event generation. The mode of (events enabled/events disabled) is saved by the device and restored after the request has been satisfied. The request data does not go into the event queue, but into a separate virtual register.

Use inquire_request_status to determine whether a previously posted request is ready.

To discard a request that was previously posted and satisfied, but which has not been read, use request_choice, request_locator, or intrequest_locator2d with a zero timeout and discard the result.

Integer operations are only available when using the INT_XFORM gopen mode. When in INT_XFORM mode, floating point operations are not available for that fildes. Floating point operations are the default, or can be specified with FLOAT_XFORM mode. For a list of integer operations, floating point operations and common operations see the starbase(3G) manual page.

Museum