INQUIRE DEFAULT LOCATOR DEVICE DATA 3(3P) — SUNPHIGS LIBRARY

NAME

INQUIRE DEFAULT LOCATOR DEVICE DATA 3 − inquire the predefined locator data

SYNOPSIS

C Syntax

void
pinqdeflocdata3 ( type, device, size, error_ind, buffer, total_size, data )
Pwstypetype;workstation type
Pintdevice;logical input device number
Pintsize;size of application buffer
Pint∗error_ind;OUT error indicator
Pchar∗buffer;OUT pointer to buffer
Pint∗total_size;OUT actual size of buffer
Pdefloc3∗data;OUT default data

FORTRAN Syntax

SUBROUTINE pqdlc3 ( WTYPE, DEVNO, N, MLDR, ERRIND, DPX, DPY, DPZ, OL, PET, EVOL,
LDR, DATREC )
INTEGERWTYPEworkstation type
INTEGERDEVNOlogical input device number
INTEGERNlist element requested
INTEGERMLDRdimension of data record array
INTEGERERRINDOUT error indicator
REALDPX, DPY, DPZOUT default initial locator position
INTEGEROLOUT number of available prompt/echo types
INTEGERPETOUT Nth element of list of available
prompt/echo types
REALEVOL(6)OUT default echo volume in device coordinates
INTEGERLDROUT number of array elements used
in data record
CHARACTER∗80DATREC(MLDR) OUT data record

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

Use INQUIRE DEFAULT LOCATOR DEVICE DATA 3 to determine the following information for a LOCATOR input device associated with a given workstation type:

Number and list of available prompt/echo types.
Default echo volume.
Default input data record.
Default initial locator position.

Since the default prompt/echo type for all input devices is 1, the default input data record is for that prompt/echo type. There are no default input data records for prompt/echo types other than 1.

C Parameters

Applications using the C binding must allocate a buffer to be used by this function as memory space for storing portions of the device data. This buffer is passed as the buffer argument. The size of the buffer, in bytes, must be passed in the size argument. The required size is returned in the argument total_size. The caller can determine the required size by calling this function with size set to zero, in which case PHIGS will return the size needed in total_size. After allocating a buffer of the required size a subsequent call can be made to retrieve all the data.

Some values will be returned even if the buffer size specified is too small, including the case of its being zero. These values are total_size, the number of prompt/echo types, the default echo volume, and the default initial locator position. Error PEBUFSPAC (2200) is returned if size is too small, but not if it is zero.

typeA Pwstype value specifying the workstation type with which the device is associated.

devThe device number of the locator device. See the Available Devices section of INITIALIZE LOCATOR for a description of the available devices.

sizeThe size, in bytes, of buffer.

error_ind
The 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.

bufferA pointer to the buffer, allocated by the application, to be used by PHIGS to store portions of the returned data.

total_size
A pointer to an integer in which PHIGS returns the size of the buffer needed, in bytes, to return all the information.

dataA pointer to a Pdefloc3 structure in which to store the information. Pdefloc3 is defined in phigs.h as follows:

typedef struct {
Ppoint3position;/∗ initial position ∗/
Pintlstpets;/∗ list of prompt and echo types ∗/
Plimit3e_volume;/∗ default echo volume ∗/
Plocrecrecord;/∗ default locator data record ∗/
} Pdefloc3;

FORTRAN Parameters

Applications using the FORTRAN binding must supply a CHARACTER array to this function, into which will be placed the contents of the default input data record. The contents of the data record are subsequently extracted by the application with the function UNPACK DATA RECORD. The allocated dimension of the character array is passed in the MLDR argument. The dimension needed is returned in the LDR argument. The caller can determine the required dimension by calling this function with MLDR set to zero, in which case PHIGS will return the dimension needed in LDR.

Even if the dimension specified in MLDR is too small, including the case of its being zero, some values will be returned. These are LDR, the number of available prompt/echo types, the prompt/echo type list entry requested, the echo volume, and the default initial locator position. Error 2001 is returned if MLDR is too small, but not if it’s zero.

The FORTRAN function does not return the complete list of prompt/echo types. Instead, it returns only one element of this list. The element to return is indicated by the calling program via the argument N.

TYPEThe workstation type with which the device is associated.

DEVNO
The device number of the LOCATOR device. See the Available Devices section of INITIALIZE LOCATOR 3 for a description of the available devices.

NThe index of the prompt/echo type list entry to return.

MLDR
The dimension of the data record array, DATREC.

ERRIND
The 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.

DPX, DPY, DPZ
The default initial locator position.

OLThe number of available prompt/echo types.

PETThe prompt/echo type corresponding to the Nth position in the list of prompt/echo types.

EVOLAn array in which to place the limits of the echo volume, XMIN, XMAX, YMIN, YMAX, ZMIN, ZMAX.

LDRThe required dimension of the data record array, DATREC.

DATREC
The data record array. This must subsequently be passed to UNPACK DATA RECORD to access its contents.

Execution

INQUIRE DEFAULT LOCATOR DEVICE DATA 3 returns the default data of the specified locator device. This data is stored in the workstation description table associated with the workstation type. See INITIALIZE LOCATOR 3 for a description of the prompt/echo types, echo volume and data record contents and how to set these values.

Except in the cases mentioned in the C and FORTRAN Parameters sections above, if an error is detected by this function the error indicator will indicate the error number of the error detected and no other output data will be returned. If no error is detected, the error indicator will be 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

002Ignoring function, function requires state (PHOP, ∗, ∗, ∗)

052Ignoring function, workstation type not recognized by the implementation

051Ignoring function, this information is not yet available for this workstation type; open a workstation of this type and use the specific workstation type

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

2200C: Buffer overflow in input or inquiry function

2001FORTRAN: Ignoring function, output parameter size insufficient -- a FORTRAN array or string being passed as an output parameter is too small to contain the returned value.

Museum