1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
.\"##
.\" $XConsortium: p262,v 5.1 91/02/16 09:41:52 rws Exp $
.\"##
.\"##
$XMCOPY
.\"## Copyright (c) 1990, 1991 by Sun Microsystems, Inc.
.\"##
.\"## All Rights Reserved
.\"##
.\"## Permission to use, copy, modify, and distribute this software and its
.\"## documentation for any purpose and without fee is hereby granted,
.\"## provided that the above copyright notice appear in all copies and that
.\"## both that copyright notice and this permission notice appear in
.\"## supporting documentation, and that the name of Sun Microsystems,
.\"## not be used in advertising or publicity
.\"## pertaining to distribution of the software without specific, written
.\"## prior permission.
.\"##
.\"## SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
.\"## INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
.\"## EVENT SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
.\"## CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
.\"## USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
.\"## OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\"## PERFORMANCE OF THIS SOFTWARE.
.TH "RETRIEVE PATHS TO ANCESTORS" 3P "29 February 1991"
.SH NAME
RETRIEVE PATHS TO ANCESTORS \- retrieve the ancestors of the specified
structure from an archive file
.IX "Archive Files" "RETRIEVE PATHS TO ANCESTORS"
.IX "Structure Networks" "RETRIEVE PATHS TO ANCESTORS"
.SH SYNOPSIS
.SS C Syntax
.ft B
.ta 1.5i 3i
.nf
void
pret_paths_ances ( ar_id, struct_id, po, pd, store, paths, status )
Pint ar_id; \fIarchive identifier\fP
Pint struct_id; \fIstructure identifier\fP
Ppath_order po; \fIpath order\fP
Pint pd; \fIpath depth\fP
Pstore store; \fIhandle to store object\fP
Pelem_ref_list_list **paths; \fI\s-2OUT\s+2 structure path list\fP
Pint *status; \fI\s-2OUT\s+2 status of retrieval\fP
.fi
.ft R
.SS Required PHIGS Operating States
(PHOP, *, *, AROP)
.SH DESCRIPTION
.SS Purpose
Use \s-2RETRIEVE PATHS TO ANCESTORS\s+2 to determine the path or paths
in the specified archive file which reference the specified structure.
It performs the same function in \s-2PEX-SI\s0 as
\s-2RETRIEVE PATHS TO ANCESTORS\s+2 does in standard \s-2PHIGS\s+2.
.SS C Input Parameters
Applications using the \s-2C\s+2 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 \fIstore\fP argument.
.LP
The store buffer is a data area managed by \s-2PHIGS\s+2. While the application
is responsible for creating the inital buffer through a call to \s-2\CREATE STORE\s+2,
\s-2PHIGS\s+2 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 \fIpaths\fR.
.IP \fIar_id\fP
Identifier of the archive file from which to retrieve structure path data.
.IP \fIstruct_id\fP
Identifier of the structure whose ancestors are to be retrieved.
.IP \fIpo\fP
Order in which the path lists are to be returned.
Valid values defined in phigs.h are:
.sp .2
.ta .5i
.nf
PORDER_TOP_FIRST
PORDER_BOTTOM_FIRST
.fi
.sp .2
.IP \fIpd\fP
Depth (maximum number of references) of path lists to return.
.IP \fIstore\fP
The memory buffer \s-2PHIGS\s+2 is to use for storing the information
returned.
This buffer must exist prior to calling this function (see
\s-2CREATE STORE (3P)\s+2).
.SS C Output Parameters
.IP \fIpaths\fP
A 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:
.sp .4
.ta .5i +\w'Pelem_ref_list 'u +\w'num_elem_ref_lists; 'u
.nf
typedef struct{
.sp .2
Pint num_elem_ref_lists; /* number of execute reference lists */
Pelem_ref_list *elem_ref_lists; /* list of execute reference lists */
.sp .2
} Pelem_ref_list_list;
.fi
.sp
The \fInum_elem_ref_lists\fP component specifies the number of structure path lists,
or execute reference lists.
.IP
The \fIelem_ref_lists\fP component is a pointer to
a list, \fInum_elem_ref_lists\fP long, of Pelem_ref_list structures,
containing the specified structure's execute reference lists.
Pelem_ref_list is defined in phigs.h as follows:
.sp .4
.ta .5i +\w'Pelem_ref 'u +\w'num_elem_refs; 'u
.nf
typedef struct{
.sp .2
Pint num_elem_refs; /* number of execute references */
Pelem_ref *elem_refs; /* list of execute references */
.sp .2
} Pelem_ref_list;
.fi
.sp
\fIelem_refs\fP is a pointer to a list \fInum_elem_refs\fP 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:
.sp .4
.ta .5i +\w'Pint 'u +\w'elem_pos; 'u
.nf
typedef struct {
.sp .2
Pint struct_id; /* structure identifier */
Pint elem_pos; /* element number */
.sp .2
} Pelem_ref;
.fi
.IP \fIstatus\fP
An integer used for returning the success or failure of the routine.
.SS Execution
When \s-2RETRIEVE PATHS TO ANCESTORS\s+2 is called,
\fIstructure path list\fP is
filled with list(s) identifying the \s-2EXECUTE STRUCTURE\s+2 structure
elements that refer to \fIstructure identifier\fP,
in the order of traversal.
These \s-2EXECUTE STRUCTURE\s+2 structure elements are represented as
(\fIstructure identifier\fP, element position) pairs, giving the parent structure
identifier and the position of the \s-2EXECUTE STRUCTURE\s+2 structure element.
Whenever \fIstructure identifier\fP itself is included at the bottom
of a returned path of ancestors, it is represented by a
(\fIstructure identifier\fP, element position) pair
with an element position of 0.
\fIpath order\fP and \fIpath depth\fP are used to determine the portion
of each path returned.
The number of references returned in each path is specified by
\fIpath depth\fP;
a \fIpath depth\fP of 0 returns all the references in the path.
In case of truncation, \fIpath order\fP determines whether the head
(\fItop first\fP) or the tail (\fIbottom first\fP) 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.
.LP
For example, specifying \fItop first\fP and a depth of 0 returns all
paths to \fIstructure identifier\fP. Specifying \fItop first\fP
and a depth of 1 returns the root of each structure network that
references \fIstructure identifier\fP. Specifying \fIbottom first\fP and a depth of
2 returns all the parents of \fIstructure identifier\fP.
.SH ERRORS
.IP 007
Ignoring function, function requires state
(\s-2PHOP\s+2, \s-2*\s+2, \s-2*\s+2, \s-2AROP\s+2)
.IP 201
Ignoring function, the specified structure does not exist
.IP 207
Ignoring function, the specified path depth is less than zero
.SH SEE ALSO
.nf
.IP
.ta 0.5i
.SM "OPEN ARCHIVE FILE (3P)"
.SM "ARCHIVE STRUCTURE NETWORKS (3P)"
.SM "SET CONFLICT RESOLUTION (3P)"
.SM "INQUIRE ALL CONFLICTING STRUCTURES (3P)"
.SM "INQUIRE CONFLICTING STRUCTURES IN NETWORK (3P)"
.SM "RETRIEVE PATHS TO DESCENDANTS (3P)"
.SM "RETRIEVE STRUCTURE NETWORKS (3P)"
.SM "DELETE STRUCTURE NETWORKS FROM ARCHIVE (3P)"
.SM "CREATE STORE (3P)"
.SM "DELETE STORE (3P)"
.fi
|
