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



Use Inquire Paths to Ancestors to inquire the ancestral paths of a specified structure. A path of ancestors of a structure S is a list of ordered pairs: ((A1,E1),(A2,E2),...,(Am,Em&# 41;, (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 (i.e., 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. Your application may 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 may 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 of the returned path portions are distinct.

If the information is available, then the graPHIGS API sets the error indicator to zero and returns the values in the output parameters. If the information is unavailable, then the values returned in the output parameters are unpredictable and the graPHIGS API sets the error indicator to one of the following errors:

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

Language Bindings


pinq_paths_ances (struct_id, order, depth, store, err_ind, paths)

Input Parameters

Pint struct_id
Structure identifier.

Ppath_order order

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 Create Store ( CREATE STORE (PHOP,*,*,*)) subroutine for details on how the graPHIGS API uses this parameter on inquiries.

Output Parameters

Pint *err_ind
Error indicator.

Pelem_ref_list_list **paths
Structure path list. The memory referenced by *paths is managed by the parameter store.


PQPAN (strid, pthord, pthdep, ipthsz, n, errind, ol, apthsz, paths)

Input Parameters

integer strid
Structure identifier.

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

integer pthdep
Path depth (>=0).

integer ipthsz
Maximum number of path entries the buffer can contain.

integer n
Element of the list of paths.

Output Parameters

integer errind
Error indicator.

integer ol
Number of paths available.

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

integer paths(2,ipthsz)
nth structure path.



Related Subroutines

  • Inquire Paths To Descendants

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