GPHIGS C FUNCTIONS - RETRIEVE PATHS TO DESCENDANTS

RETRIEVE PATHS TO DESCENDANTS

PRET_PATHS_DESCS

CALL SEQUENCE

void pret_paths_descs(

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 are reference by the structure struct_id.

The complete path of descendant of a structure S is represented by a series of couplets: ((S, E0), (D1, E1), (D2, E2), ..., (DN, 0))

where D_n indicates the structure ID of the descendant and E_n indicates the element number of an EXECUTE STRUCTURE element of a single path. Each (D_i, E_i) structure element references structure element (D_i+1, E_i+1), from the highest parent structure (S, E0), defined by struct_id, down to (DN, 0) the bottom-most structure. DN 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) from the specified structure.

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

Specify path depth = 1 and path order = PORDER_BOTTOM_FIRST to return a list of all of the lowest-level structures in the structure network.

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)