INQUIRE PICK DEVICE STATE 3(3P) — SUNPHIGS LIBRARY

NAME

INQUIRE PICK DEVICE STATE 3 − inquire state of a pick device

SYNOPSIS

C Syntax

void
pinqpickst3 ( ws, dev, type, size, error_ind, buffer, total_size, state )
Pintws;workstation identifier
Pintdev;pick device number
Pinqtypetype;type of returned value
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
Ppickst3∗state;OUT pick device state

FORTRAN Syntax

SUBROUTINE pqpks3 ( WKID, PKDNR, TYPE, MLDR, IPISSZ, IPESSZ, IPPSZ, ERRIND, MODE,
ESW, PISSZ, PIS, PESSZ, PES, ISTAT, PPD, PP, PET, EVOL, LDR, DATREC, PPORDR )
INTEGERWKIDworkstation identifier
INTEGERPKDNRpick device number
INTEGERTYPEtype of returned values (PSET, PREALI)
INTEGERMLDRdimension of data record array
INTEGERIPISSZpick inclusion set buffer size
INTEGERIPESSZpick exclusion set buffer size
INTEGERIPPSZpick path buffer size
INTEGERERRINDOUT error indicator
INTEGERMODEOUT operating mode (PREQU, PSAMPL, PEVENT)
INTEGERESWOUT echo switch (PNECHO, PECHO)
INTEGERPISSZOUT pick inclusion set size
INTEGERPIS(IPISSZ)OUT pick inclusion set
INTEGERPESSZOUT pick exclusion set size
INTEGERPES(IPESSZ)OUT pick exclusion set
INTEGERISTATOUT initial status (POK, PNPICK)
INTEGERPPDOUT pick path depth
INTEGERPP(3, IPPSZ)OUT pick path
INTEGERPETOUT prompt/echo type
REALEVOL(6)OUT echo volume in device coordinates
INTEGERLDROUT number of array elements used
in data record
CHARACTER∗80DATREC(MLDR) OUT data record
INTEGERPPORDROUT pick path order (PPOTOP, PPOBOT)

Required PHIGS Operating States

(PHOP, WSOP, ∗, ∗)

DESCRIPTION

Purpose

Use INQUIRE PICK DEVICE STATE 3 to determine the current state of the specified pick device.

C Input Parameters

Applications using the C binding must allocate 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 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. The size in general will not be zero, but in some cases it may be, depending on the device state.

Even if the buffer size specified is too small, including the case of its being zero, some values will be returned. These are the total_size, the operating mode, the echo switch, the prompt/echo type and the echo volume. Error PEBUFSPAC (2200) is returned if size is too small, but not if it’s zero.

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

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

typeAn enumerated value specifying whether the inquired values are to be returned as the values originally specified by the application (SET), or as the values actually being used by the workstation if any of the application-specified values had to be mapped to ones available on the workstation (REALIZED). Valid values are defined in phigs.h as:

PSET(return application-specified value)
PREALIZED(return value available on the workstation)

A value of PSET is currently ignored.

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.

stateA pointer to a Ppickst3 structure containing the current state of the specified pick device. Ppickst3 is defined in phigs.h as follows:

typedef struct {
Pimodemode;/∗ operating mode ∗/
Peswesw;/∗ echo switch ∗/
Pintlstinclusion_filter;/∗ pick inclusion filter ∗/
Pintlstexclusion_filter;/∗ pick exclusion filter ∗/
Ppickpick;/∗ pick path and status ∗/
Pintpet;/∗ prompt/echo type ∗/
Plimite_area;/∗ echo area ∗/
Ppickrecrecord;/∗ data record ∗/
Ppathorderorder;/∗ path order ∗/
} Ppickst3;

FORTRAN Input Parameters

Applications using the FORTRAN binding must supply a CHARACTER array to this function, into which will be placed the contents of the device’s 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, and all the data not in the data record.

Error 2001 is returned if MLDR is too small, but not if it’s zero.

INQUIRE PICK DEVICE STATE 3 returns a number of variable length lists. Parameters to the function exist for both the allocated size of the lists and the actual size needed to return all the data. If any of the allocated sizes are too small to accept the entire list, the corresponding list will not be returned. The required size of the list, however, will be returned. The error indicator will be set to error 2001 in such a case.

WKIDThe workstation identifier of the workstation associated with the device.

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

TYPEAn enumerated value specifying whether the inquired values are to be returned as the values originally specified by the application (SET), or as the values actually being used by the workstation if any of the application-specified values had to be mapped to ones available on the workstation (REALIZED). Valid values are defined in phigs77.h as:

PSET(return application-specified value)
PREALI(return value available on the workstation)

A value of PSET is currently ignored.

IPISSZ, IPESSZ
The size of the pick filter inclusion and exclusion set buffers.

IPPSZThe pick path buffer size.

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.

MODE
The operating mode.

ESWThe echo switch.

PISSZThe actual pick inclusion set size.

PISThe pick filter inclusion set.

PESSZ
The actual pick inclusion set size.

PESThe pick filter inclusion set.

MLDR
The dimension of the data record array, DATREC.

ISTATThe initial pick status.

PPDThe initial pick path depth.

PPThe initial pick path.

PETThe prompt/echo type.

EVOLAn array containing 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.

PPORDR
The pick path order.

Execution

INQUIRE PICK DEVICE STATE 3 returns the current state of the specified pick 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 pick, prompt/echo type, echo volume, pick path order, data record, and pick filter. See SET PICK MODE for a description of the operating mode and the echo switch and how to set these values. See INITIALIZE PICK 3 for a description of the initial pick, prompt/echo type, echo volume, pick path order, and data record contents and how to set these values. See SET PICK FILTER for a description of the pick filter and how to set it.

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

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

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