graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPQEDA - Inquire List of Element Data for any Structure

GPQEDA (strid, start, 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 GPQEDA to inquire the contents of one or more sequential structure elements from a specified structure and element position. The elements will be returned in the format that is described in The graPHIGS Programming Interface: Technical Reference If the specified element position is greater than the number of elements in the structure or is less than one then the error indicator will be non-zero.

If the inquired information is available, the error indicator is returned as zero, and the values are returned in the output parameters. If the inquired information is unavailable, the error indicator 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 the same as that returned by the Inquire Element Data (GPQED) subroutine.

Parameters

strid -- specified by user, fullword integer

Structure identifier.

start -- specified by user, fullword integer

The position of the first element whose element data is to be returned (>=1)

number -- specified by user, fullword integer

Number of elements requested (>=1)

buflen -- specified by user, fullword integer

Length in bytes of the data parameter.

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:

12: FUNCTION REQUIRES STATE SSSL
122: STRUCTURE IDENTIFIER DOES NOT EXIST
524: ELEMENT POSITION > NUMBER OF ELEMENTS IN STRUCTURE
538: START VALUE < ONE
540: REQUESTED NUMBER < ONE
577: BUFFER LENGTH IS < ZERO

actnum -- returned by the graPHIGS API, fullword integer

Total number of elements actually returned.

actlen -- returned by the graPHIGS API, fullword integer

Total length in bytes of the element data returned in the data parameter.

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 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 would not fit into the inbound buffer between the nucleus and the shell. actnum contains 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

GPQED: Inquire List of Element Data
GPQEHD: Inquire List of Element Headers

RCP code

201337103 (X'0C00290F')