[ Previous | Next | Contents | Glossary | Home | Search ]
The graPHIGS Programming Interface: ISO PHIGS Subroutine Reference

RETRIEVE PATHS TO ANCESTORS (PHOP,*,*,AROP)

Purpose

Use Retrieve Paths to Ancestors to retrieve the ancestral paths of the 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., 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. Your application can specify the path order as TOP_FIRST or BOTTOM_FIRST. 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.

Language Bindings

C

pret_paths_ances (ar_id, struct_id, order, depth, store, paths)

Input Parameters

Pint ar_id
Archive file identifier.

Pint struct_id
Structure identifier.

Ppath_order order
Path order (0=PORDER_TOP_FIRST, 1=PORDER_BOTTOM_FIRST).

Pint depth
Path depth (>=0).

Pstore store
Handle to the store object. The graPHIGS API uses an object of type Store to facilitate the use of subroutines which return complex data. See the Create Store subroutine for details on how the graPHIGS API uses this parameter.

Output Parameters

Pelem_ref_list_list **paths
Structure path list. The memory referenced by *paths is managed by Store. If an error occurs, then *paths is set to NULL.

FORTRAN

PREPAN (afid, strid, pthord, pthdep, ipthsz, n, ol, apthsz, paths)

Input Parameters

integer afid
Archive file identifier.

integer strid
Structure identifier.

integer pthord
Path order (0=PPOTOP, 1=PPOBOT).

integer pthdep
Path depth (>=0).

integer ipthsz
Maximum number of path entries that the buffer can hold.

integer n
Element of the list of paths.

Output Parameters

integer ol
Number of paths available

integer apthsz
Actual number of entries in the nth structure path.

integer paths(2,ipthsz)
nth structure path.

Errors

7
Function Requires State (PHOP,*,*,AROP)
201
Specified Structure Does Not Exist
207
Specified Path Depth < Zero

Related Subroutines

  • Retrieve Paths To Descendants

    • [ Previous | Next | Contents | Glossary | Home | Search ]