graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPQPAS - Inquire Ancestors of Structure

GPQPAS (strid, order, depth, start, number, buflen, errind, actnum, actlen totnum, data, termcond)

Note:

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

Purpose

Use GPQPAS to inquire the ancestral paths of a specified structure from the currently selected structure store. A path of ancestors of a structure S is a list of ordered pairs ((A1, E1), (A2, E2), (S,0)) where each ordered pair consists of an identifier of a structure (Ax) that is an ancestor of the specified structure (S) and the position of an execute structure-type element (Ex) that references the next structure in the path. Ancestor structure A1 is the top of the path (e.g., it is not referenced by any other structure) and S is the bottom of the path.

The path order and path depth determine the portion of each path to be returned. The path depth determines the maximum number of ordered pairs returned in any one path. Specifying a path depth of zero returns each path in its entirety. When truncation occurs, the path order determines whether the head or tail portion of the path is returned. This truncation may result in two or more portions of paths having the same set of element references. Only one such portion is returned so that all of the returned path portions are distinct.

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 error indicator is 543 (the start value exceeds the extent of the available data), then only the total number (totnum) parameter is set. 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.

Parameters

strid -- specified by user, fullword integer

Structure identifier.

order -- specified by user, fullword integer

Path order (1=TOPFIRST, 2=BOTTOMFIRST )

depth -- specified by user, fullword integer

Path depth (>=0)

start -- specified by user, fullword integer

Starting member of the list of paths (>=1)

number -- specified by user, fullword integer

Number of paths requested (>=0)

buflen -- specified by user, fullword integer

Length, in bytes, of the specified data parameter (data) (>=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:

12: FUNCTION REQUIRES STATE SSSL
122: STRUCTURE IDENTIFIER DOES NOT EXIST
538: START VALUE < ONE
539: REQUESTED NUMBER < ZERO
543: START EXCEEDS DATA EXTENT. TOTAL NUMBER AVAILABLE RETURNED
552: PATH ORDER IS INVALID
558: PATH DEPTH < ZERO
577: BUFFER LENGTH IS < ZERO

actnum -- returned by the graPHIGS API, fullword integer

Total number of paths returned.

actlen -- returned by the graPHIGS API, fullword integer

Total length, in bytes, of the paths returned in the data parameter (data)

totnum -- returned by the graPHIGS API, fullword integer

Total number of the distinct paths available for the specified structure identifier.

data -- returned by the graPHIGS API, variable data

The data buffer into which the paths are to be returned. The format of the data is as follows:

                     ---------------------
   Start of buffer   |      path 1       |
                     |-------------------|
                     |      path 2       |
                     |-------------------|
                     |                   |
                     Z                   Z
                     |-------------------|
     End of buffer   |      path n       |
                     ---------------------

where each path has the following format:

                     ----------------------
          WORDS  1   |number of items in  | Fullword integer
                     | the returned path  |
                     |--------------------|
                 2   |  structure id 1    | Fullword integer
                     |--------------------|
                 3   | element number 1   | Fullword integer
                     |--------------------|
                 4   |  structure id 2    | Fullword integer
                     |--------------------|
                 5   | element number 2   | Fullword integer
                     |--------------------|
                     |                    |
                     Z                    Z
                     |--------------------|
                     |   structure id m   | Fullword integer
                     |--------------------|
                     |  element number m  | Fullword integer
                     ----------------------

termcond -- returned by the graPHIGS API, fullword integer

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

1-Count Exhausted

The requested number of paths have been returned.

2-Buffer Overflow

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

3-End of Paths

No more paths exists. This condition supersedes the Count Exhausted condition (if that condition was in effect) Because of this, the total number of paths may or may not be equal to the requested number of paths to be returned. actnum should be checked to find the actual number of paths returned.

4-Large Path

The next path would not fit into the inbound buffer between the nucleus and the shell. actnum contains the number of paths returned excluding the path that would not fit.

Error Codes

None

Related Subroutines

GPQPDS: Inquire Descendents of Structure

RCP code

201347586 (X'0C005201')