graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPQED - Inquire List of Element Data

GPQED (number, buflen, errind, actnum, actlen, data, termcond)

Note:

This subroutine is a Structure State List (SSL) inquiry. For an overview, see "SSL Inquiries"

Purpose

Use GPQED to inquire the contents of one or more sequential structure elements starting at the one pointed to by the current element pointer. The elements will be returned in the format that is described in The graPHIGS Programming Interface: Technical Reference

This subroutine does not move the element pointer.

If the inquired information is available, then the graPHIGS API sets the error indicator to zero and returns the values in the output parameters. If the inquired information is unavailable, then the error indicator (errind) contains an error number indicating the reason, and the values returned in the output parameters are unpredictable.

Note:

The format of the element data that is returned by this subroutine is different from that returned by the Inquire Element Content (GPQE) subroutine.

Parameters

number -- specified by user, fullword integer

Number of elements to be returned (>=1)

buflen -- specified by user, fullword integer

Length, in bytes, of the data area specified by data into which the returned structure elements will be placed (>=0)

errind -- returned by the graPHIGS API, fullword integer

Error indicator. If the error indicator is zero, the request has been completed. Otherwise, one of the following errors exists:

4: FUNCTION REQUIRES STATE STOP
535: CURRENT ELEMENT POINTER IS ZERO
539: REQUESTED NUMBER < ZERO
540: REQUESTED NUMBER < ONE

actnum -- returned by the graPHIGS API, fullword integer

Total number of elements that have been returned.

actlen -- returned by the graPHIGS API, fullword integer

Total length, in bytes, of the structure element data that has been returned in data

data -- returned by the graPHIGS API, variable data

The data buffer into which the structure elements are to be returned.

The structure elements are placed into this area so that the first structure element starts at the beginning of the area and each succeeding element can be reached by adding the length of the structure element to its offset into the buffer. Only complete structure elements will be returned. The format of each structure element is shown in The graPHIGS Programming Interface: Technical Reference

termcond -- returned by the graPHIGS API, fullword integer

Termination condition. The list of structure elements was terminated due to one of the following reasons:

1-Count Exhausted

The requested number of elements have been returned.

2-Buffer Overflow

The requested number of elements could not be returned because they would not all fit in the area provided. actnum will contain the actual number returned.

3-End of Structure

The last element of the structure was encountered. This condition supersedes the Count Exhausted condition (if that condition was in effect) Because of this, the total number of elements returned may or may not be equal to the requested number of elements to be returned so actnum should be checked to find the actual number of elements returned.

4-Big Element

The next element to be returned would not fit into the inbound buffer between the nucleus and shell. actnum will contain the number of elements preceding the one that would not fit. This number of elements will be in data also.

Error Codes

None

Related Subroutines

GPQE: Inquire Element Content
GPQEHD: Inquire List of Element Headers
GPQETS: Inquire Element Type and Size

RCP code

201337100 (X'0C00290C')