graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPRAS - Retrieve Ancestors to Structures

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

Note:

This subroutine is an Archive inquiry. For an overview, see "Archive Inquiries"

Purpose

Use GPRAS to retrieve the ancestral paths of a specified structure from the specified open archive file.

A path of ancestors of a structure S is a list of ordered pairs ((A1, E1), (A2,E2),..., (Am,Em), (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 that the graPHIGS API returns. 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 graPHIGS API returns the head or tail portion of the path. This truncation can result in two or more portions of paths having the same set of element references. The graPHIGS API returns only one such portion so that all 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

arid -- specified by user, fullword integer

Archive file identifier.

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 data area specified by the data parameter into which the graPHIGS API returns the paths.

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:

7: FUNCTION REQUIRES STATE AROP
122: STRUCTURE IDENTIFIER DOES NOT EXIST
220: SPECIFIED ARCHIVE FILE 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 that the graPHIGS API returns in the data parameter.

totnum -- returned by the graPHIGS API, fullword integer

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

data -- returned by the graPHIGS API, variable data

The data buffer into which the graPHIGS API returns the paths. 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 graPHIGS API terminated the list of paths due to one of the following reasons:

1- Count Exhausted

The graPHIGS API returned the requested number of paths.

2- Buffer Overflow

The graPHIGS API could not return the requested number of paths because there was not enough room in the area provided. actnum contains the actual number returned.

3- End of the Paths

No more paths exist. This condition supercedes the Count Exhausted condition (if that condition was in effect) The total number of paths returned may or may not be equal to the number of returned paths you requested. Check actnum 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 excluding the one that would not fit. This number of paths is also in the data parameter.

Error Codes

None

Related Subroutines

GPRDS: Retrieve Descendants to Structures

RCP code

201347594 ( X'0C00520A')