NAME

INQUIRE PATHS TO DESCENDANTS − inquire the descendants of the specified structure

SYNOPSIS

C Syntax

void
pinq_paths_descs ( struct_id, order, depth, store, error_ind, paths )
Pintstruct_id;structure identifier
Ppath_orderorder;path order
Pintdepth;path depth
Pstorestore;handle to Store object
Pint∗error_ind;OUT error indicator
Pelem_ref_list_list∗∗paths; OUT structure path list

Required PHIGS Operating States

(PHOP, ∗, ∗, ∗)

DESCRIPTION

Purpose

Use INQUIRE PATHS DESCENDENTS to determine the path or paths in the Central Structure Store that are referenced by the specified structure.  It performs the same function in PEX-SI as INQUIRE PATHS TO DESCENDANTS does in standard PHIGS. 

C Input Parameters

Applications using the C binding must create a buffer to be used by this function as memory space for storing data associated with the device state.  This buffer is passed as the store argument. 

The store buffer is a data area managed by PHIGS. While the application is responsible for creating the inital buffer through a call to CREATE STORE, PHIGS manages this area such that there is sufficient memory for the specific inquiry. The data record within the store buffer is accessed by the pointer pointed to by paths. 

struct_id
Identifier of the structure to be inquired for descendants.

orderOrder in which the path lists are to be returned.  This is an enumerated type defined in phigs.h to have the following values:

PORDER_TOP_FIRSTtop first
PORDER_BOTTOM_FIRST bottom first

depthDepth (maximum number of references) of path lists to return. 

storeThe memory buffer PHIGS is to use for storing the information returned.  This buffer must exist prior to calling this function (see CREATE STORE (3P)). 

C Output Parameters

error_ind
A pointer to the location to store the error number of any error detected by this function.

pathsA pointer to a pointer to a structure Pelem_ref_list_list, containing a list of the specified structure’s structure path lists.  Pelem_ref_list_list is defined in phigs.h as follows:

typedef struct{
Pintnum_elem_ref_lists;/∗ number of execute reference lists ∗/
Pelem_ref_list∗elem_ref_lists;/∗ list of execute reference lists ∗/
} Pelem_ref_list_list;

The num_elem_ref_lists component specifies the number of structure path lists or execute reference lists. The elem_ref_lists component is a pointer to a list, num_elem_ref_lists long, of Pelem_ref_list structures containing the specified structure’s execute reference lists.  Pelem_ref_list is defined in phigs.h as follows:

typedef struct{
Pintnum_elem_refs;/∗ number of execute references ∗/
Pelem_ref∗elem_refs;/∗ list of execute references ∗/
} Pelem_ref_list;

elem_refs is a pointer to a list num_elem_refs long of Pelem_ref structures containing the structure identifier and element number of each execute reference structure element in the execute reference list.  Pelem_ref is defined in phigs.h as follows:

typedef struct {
Pintstruct_id;/∗ structure identifier ∗/
Pintelem_pos; /∗ element number ∗/
} Pelem_ref;

Execution

When INQUIRE PATHS DESCENDENTS is called, paths is filled with list(s) identifying the EXECUTE STRUCTURE structure elements which are referenced by struct_id, in the order of traversal.  These EXECUTE STRUCTURE structure elements are represented as (structure identifier, element position) pairs, giving the parent structure identifier and the position of the EXECUTE STRUCTURE structure element.  The bottom-most element of a structure network, if included in a returned path, is indicated by a (structure identifier, element position) pair containing the identifier of the bottom-most structure and an element position of 0.  order and depth are used to determine the portion of each path returned.  The number of references returned in each path is specified by depth; a depth of 0 returns all the references in the path.  In case of truncation, order determines whether the head (PORDER_TOP_FIRST) or the tail (PORDER_BOTTOM_FIRST) portion of a path is returned.  If a path truncation results in two or more partial paths with the same set of element references, only one of the identical path portions is returned. 

For example, specifying PORDER_TOP_FIRST and a depth of 0 returns all paths from struct_id. Specifying PORDER_TOP_FIRST and a depth of 1 returns each EXECUTE STRUCTURE structure element in struct_id as a separate path list.  Specifying PORDER_BOTTOM_FIRST and a depth of 1 returns all the bottom-most structures of the network. 

ERRORS

002Ignoring function, function requires state (PHOP, ∗, ∗, ∗)

201Ignoring function, the specified structure does not exist

207Ignoring function, the specified path depth is less than zero

SEE ALSO

EXECUTE STRUCTURE (3P)
INQUIRE PATHS TO ANCESTORS (3P)
CREATE STORE (3P)
DELETE STORE (3P)

September 02, 1992