NAME

RETRIEVE PATHS TO ANCESTORS − retrieve the ancestors of the specified structure from an archive file

SYNOPSIS

C Syntax

void
pret_paths_ances ( ar_id, struct_id, po, pd, store, paths, status )
Pintar_id;archive identifier
Pintstruct_id;structure identifier
Ppath_orderpo;path order
Pintpd;path depth
Pstorestore;handle to store object
Pelem_ref_list_list∗∗paths; OUT structure path list
Pint∗status;OUT status of retrieval

Required PHIGS Operating States

(PHOP, ∗, ∗, AROP)

DESCRIPTION

Purpose

Use RETRIEVE PATHS TO ANCESTORS to determine the path or paths in the specified archive file which reference the specified structure.  It performs the same function in PEX-SI as RETRIEVE 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. 

ar_idIdentifier of the archive file from which to retrieve structure path data. 

struct_id
Identifier of the structure whose ancestors are to be retrieved.

poOrder in which the path lists are to be returned.  Valid values defined in phigs.h are:

PORDER_TOP_FIRST
PORDER_BOTTOM_FIRST

pdDepth (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

pathsA 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;

statusAn integer used for returning the success or failure of the routine. 

Execution

When RETRIEVE PATHS TO ANCESTORS is called, structure path list is filled with list(s) identifying the EXECUTE STRUCTURE structure elements that refer to structure identifier, 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 structure identifier 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.  path order and path depth are used to determine the portion of each path returned.  The number of references returned in each path is specified by path depth; a path depth of 0 returns all the references in the path.  In case of truncation, path order determines whether the head (top first) or the tail (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 top first and a depth of 0 returns all paths to structure identifier. Specifying top first and a depth of 1 returns the root of each structure network that references structure identifier. Specifying bottom first and a depth of 2 returns all the parents of structure identifier. 

ERRORS

007Ignoring function, function requires state (PHOP, ∗, ∗, AROP)

201Ignoring function, the specified structure does not exist

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

SEE ALSO

OPEN ARCHIVE FILE (3P)
ARCHIVE STRUCTURE NETWORKS (3P)
SET CONFLICT RESOLUTION (3P)
INQUIRE ALL CONFLICTING STRUCTURES (3P)
INQUIRE CONFLICTING STRUCTURES IN NETWORK (3P)
RETRIEVE PATHS TO DESCENDANTS (3P)
RETRIEVE STRUCTURE NETWORKS (3P)
DELETE STRUCTURE NETWORKS FROM ARCHIVE (3P)
CREATE STORE (3P)
DELETE STORE (3P)

September 02, 1992