GPHIGS C FUNCTIONS - RETRIEVE PATHS TO ANCESTORS

RETRIEVE PATHS TO ANCESTORS

PRET_PATHS_ANCES

CALL SEQUENCE

void pret_paths_ances(

Pint	archive_id	/* archive identifier	*/
Pint	struct_id	/* structure identifier	*/
Ppath_order	order	/* path order	*/
Pint	depth	/* path depth	*/
Pstore	store	/* (out) handle to Store object	*/
Pelem_ref_list_list	**paths	/* (out) structure path list	*/

TYPES

typedef enum {
	PORDER_TOP_FIRST, 
	PORDER_BOTTOM_FIRST
} Ppath_order ;

typedef void * Pstore;

typedef struct {
	Pint	num_elem_ref_lists;	/* number of element reference lists 	*/
	Pelem_ref_list	*elem_ref_lists;	/* list of element reference lists 	*/
} Pelem_ref_list_list;

typedef struct {
	Pint 	num_elem_refs;	/* number of element references 	*/
	Pelem_ref 	*elem_refs;	/* list of element references	*/
} Pelem_ref_list;

typedef struct {
	Pint 	struct_id;	/* structure identifier 	*/
	Pint 	elem_pos;	/* element position 	*/
} Pelem_ref;

PHIGS STATE

(PHOP, *, *, AROP).

EFFECT

Returns the list of paths in the archive file that reference the structure struct_id.

The complete path of ancestors of a structure S is represented by a series of couplets: ((A₁, E₁), (A₂, E₂), ... (S, 0))

where A_n indicates the structure ID of the ancestor and E_n indicates the element number of an EXECUTE STRUCTURE element of a single path. Each (A_i, E_i) structure element references structure element (A_i+1, E_i+1), from the highest parent structure, down to (S, 0) the lowest structure, defined by struct_id. A1 is a structure which is not referenced by any EXECUTE STRUCTURE in the archive.

The path and order determine the position of each path to be returned.

Specify path depth = 0 to return each entire path.

Specify path depth = 0 and path order = PORDER_TOP_FIRST to return a list of all paths (that are not identical) to the specified structure.

Specify path depth = 1 and path order = PORDER_TOP_FIRST to return a list of all element references at the head of a path to the specified structure.

Specify path depth = 2 and path order = PORDER_BOTTOM_FIRST to return a list of all element references to the specified structure.

Before calling this function, the store parameter must be created by CREATE STORE

See GPHIGS user guide for details on memory management.

ERRORS

7: Ignoring function, function requires state (PHOP, *, *, AROP)
201: Ignoring function, the specified structure does not exist
207: Ignoring function, the specified path depth is less than zero (0)