RETRIEVE DESCENDANTS OF STRUCTURE(3P) — SUNPHIGS LIBRARY

NAME

RETRIEVE DESCENDANTS OF STRUCTURE − retrieve the descendants of the specified structure from an archive file

SYNOPSIS

C Syntax

void
pretrievedescstruct ( ar_id, struct_id, po, pd, size, buffer, total_size, paths )
Pintar_id;archive identifier
Pintstruct_id;structure identifier
Ppathorderpo;path order
Pintpd;path depth
Pintsize;size of application buffer
Pchar∗buffer;OUT pointer to buffer
Pint∗total_size;OUT actual size of buffer
Pexecreflstlst∗paths;OUT structure path list

FORTRAN Syntax

SUBROUTINE prdest ( AFID, STRID, PTHORD, PTHDEP, IPTHSZ, N, OL, APTHSZ, PATHS )
INTEGERAFIDarchive file identifier
INTEGERSTRIDstructure identifier
INTEGERPTHORDpath order (PPOTOP, PPOBOT)
INTEGERPTHDEPpath depth
INTEGERIPTHSZsize of path buffer
INTEGERNelement of list of paths
INTEGEROLOUT number of paths available
INTEGERAPTHSZOUT actual size of the Nth structure path
INTEGERPATHS(2, IPTHSZ)OUT Nth structure path

Required PHIGS Operating States

(PHOP, ∗, ∗, AROP)

DESCRIPTION

Purpose

Use RETRIEVE DESCENDANTS OF STRUCTURE to determine the path or paths in the specified archive file that are referenced by the specified structure.

C Input Parameters

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

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

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

PTOP_FIRST
PBOTTOM_FIRST

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

sizeSize, in number of bytes, of the application supplied buffer in which the returned values will be stored.

C Output Parameters

bufferA pointer to the buffer (of size size bytes) in which the path lists are to be returned. Note: The buffer is for use by the system. The system assigns the appropriate pointers within the paths parameter to the memory space pointed to by buffer. The application accesses the returned information through the paths parameter. If the buffer allocated is not large enough to hold all of paths, none of the information is returned, but total_size is returned with the number of bytes needed. If you call RETRIEVE DESCENDANTS OF STRUCTURE with a buffer size of 0, total_size is returned with the size of the buffer that you will need to allocate. Error 2200 is generated if the buffer size is too small, but not if it’s zero.

total_size
A pointer which returns the actual size of the buffer needed to return all the information requested.

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

typedef struct{
Pintnumber;/∗ number of execute reference lists ∗/
Pexecreflst∗erls;/∗ list of execute reference lists ∗/
} Pexecreflstlst;

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

typedef struct{
Pintnumber;/∗ number of execute references ∗/
Pexecref∗ers;/∗ list of execute references ∗/
} Pexecreflst;

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

typedef struct {
Pintstruct_id;/∗ structure identifier ∗/
Pintelem_num;/∗ element number ∗/
} Pexecref;

FORTRAN Input Parameters

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

STRID
Identifier of the structure whose descendants are to be retrieved.

PTHORD
Order in which the structure path is to be returned. Valid values (defined in phigs77.h) are:

PPOTOP(top first)
PPOBOT(bottom first)

PTHDEP
Depth (maximum number of references) of the structure path to return.

IPTHSZ
Size of the PATHS array in which the returned structure path data will be stored. If this value is smaller than the actual size of the structure path (APTHSZ), no data will be returned in the PATHS array, but APTHSZ will be set to indicate the array size required. If you call this function with an array size of zero, APTHSZ is returned with the required array size. Error 2001 is generated if IPTHSZ is too small, but not if it’s zero.

NList element of structure paths list to return; only one structure path may be retrieved per subroutine call. If a value of 0 is used here, no structure path data will be returned, but the total number of structure paths will be returned in OL.

FORTRAN Output Parameters

OLThe total number of structure paths for this structure identifier.

APTHSZ
The number of structure path elements returned in PATHS.

PATHS
A 2 x IPTHSZ integer array containing the Nth structure path for the specified structure, where the (1,∗) components contain the structure identifiers, and the (2,∗) components contain the element sequence numbers.

Execution

When RETRIEVE DESCENDANTS OF STRUCTURES is called, structure path list is filled with list(s) identifying the EXECUTE STRUCTURE structure elements which are referenced by 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. 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. 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 from struct_id. Specifying TOP_FIRST and a depth of 1 returns each EXECUTE STRUCTURE structure element in struct_id as a separate path list. Specifying BOTTOM_FIRST and a depth of 1 returns all the bottom-most structures of the network.

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

Museum