NAME

INQUIRE PATHS TO ANCESTORS − inquire the ancestors of the specified structure

SYNOPSIS

C Syntax

void
pinq_paths_ances ( 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

INQUIRE PATHS TO ANCESTORS determines the path or paths in the Central Structure Store that reference the specified structure.  It performs the same function in PEX-SI as INQUIRE PATHS TO ANCESTORS 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 ancestors.

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_FIRSTbottom 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 Pelem_ref_list_list structure which contains 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∗ex_ref_list;/∗ 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 ex_ref_list 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 TO ANCESTORSS is called, paths is filled with list(s) identifying the EXECUTE STRUCTURE structure elements which refer to 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.  Whenever struct_id itself is included at the bottom of a returned path of ancestors, it is represented by a (structure identifier, element position) pair with 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 to struct_id. Specifying PORDER_TOP_FIRST and a depth of 1 returns the root of each structure network that references struct_id. Specifying PORDER_BOTTOM_FIRST and a depth of 2 returns all the parents of struct_id. 

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 DESCENDENTS (3P)
CREATE STORE (3P)
DELETE STORE (3P)

September 02, 1992