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

INQUIRE PATHS TO DESCENDANTS (PHOP,*,*,*)

Purpose

Use Inquire Paths to Descendants to inquire the descendant paths of a specified structure. A path of descendants of a structure S is a list of ordered pairs: ((S,E0),(D1,E1),(D2,E2), ...,(Dn,0)), where each ordered pair consists of an identifier of a structure (Dx) that is a descendant of the specified structure (S) and the position of an execute structure-type element (Ex) that references the next structure in the path. The specified structure S is the top of the path and descendant structure Dn is the bottom of the path (i.e., it does not reference any other structure).

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:

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

Language Bindings

C

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

Input Parameters

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 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.

FORTRAN

PQPDE (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.

Errors

None

Related Subroutines

  • Inquire Paths To Ancestors

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