1 09/22/86 archive_
2
3 The archive_ subroutine is used to access individual components in
4 archives, list the components of an archive, and obtain information
5 about archive components.
6
7
8 Entry points in archive_:
9 List is generated by the help command
10
11
12 :Entry: get_component: 03/18/81 archive_$get_component
13
14
15 Function: This entry, given a pointer to an archive and its bitcount,
16 and the name of the desired component in the archive, returns a pointer
17 to the component and the bitcount of the component.
18
19
20 Syntax:
21 dcl archive_$get_component entry pointer fixed bin 24 char *
22 pointer fixed bin 24 fixed bin 35;
23 call archive_$get_component archive_ptr archive_bc component_name
24 component_ptr component_bc code;
25
26
27 Arguments:
28 archive_ptr
29 is a pointer to the base of the archive segment to be searched. It
30 need not point to the base of a segment; it is converted to a
31 segment base pointer by archive_, so a pointer to anywhere in the
32 segment may be given here. Input
33 archive_bc
34 is the bitcount of the archive segment. Input
35 component_name
36 is the name of the component to be searched for. It may be up to
37 32 characters long. Input
38 component_ptr
39 is a pointer to the first word of the archive component if the
40 specified component was found, or null otherwise. It is a pointer
41 into the segment pointed to by archive_ptr. Output
42
43
44 component_bc
45 is the bitcount of the archive component pointed to by
46 component_ptr. It describes a region of the archive segment which
47 contains the specified component; if an attempt is made to reference
48 past the end of this area, invalid data may be referenced. Output
49 code
50 is a standard system status code, one of the following: Output
51 error_table_$no_component
52 error_table_$not_archive
53 error_table_$archive_fmt_err
54
55
56 :Entry: get_component_info: 03/18/81 archive_$get_component_info
57
58
59 Function: This entry, given a pointer to an archive and its bitcount,
60 and the name of the desired component in the archive, fills in a
61 caller-supplied structure with information describing the archive
62 component. Also see archive_$get_component and
63 archive_$next_component_info.
64
65
66 Syntax:
67 dcl archive_$get_component_info entry pointer fixed bin 24 char
68 * pointer fixed bin 35;
69 call archive_$get_component_info archive_ptr archive_bc
70 component_name archive_component_info_ptr code;
71
72
73 Arguments:
74 archive_ptr
75 is a pointer to the base of the archive segment to be searched. It
76 need not point to the base of a segment; it is converted to a
77 segment base pointer by archive_, so a pointer to anywhere in the
78 segment may be given here. Input
79 archive_bc
80 is the bitcount of the archive segment. Input
81 component_name
82 is the name of the component to be searched for. It may be up to
83 32 characters long. Input
84
85
86 archive_component_info_ptr
87 is a pointer to a user-supplied archive_component_info structure,
88 described below. The caller must have previously set
89 archive_component_info.version to the appropriate version number,
90 currently ARCHIVE_COMPONENT_INFO_VERSION_1. The structure is filled
91 in with information describing the selected archive component if it
92 can be found. Input
93 code
94 is a standard system status code. Output It may be one of the
95 following:
96 error_table_$no_component
97 error_table_$not_archive
98 error_table_$archive_fmt_err
99 error_table_$unimplemented_version
100
101
102 Structure:
103 The archive_component_info_ptr points to the following structure
104 described in the archive_component_info.incl.pl1 include file:
105
106 dcl 1 archive_component_info aligned based
107 archive_component_info_ptr,
108 2 version fixed bin,
109 2 comp_bc fixed bin 24,
110 2 comp_ptr ptr,
111 2 name char 32 unaligned,
112 2 time_modified fixed bin 71,
113 2 time_updated fixed bin 71,
114 2 comp_lth fixed bin 19,
115 2 access bit 36 unaligned;
116
117
118 List of structure elements:
119 version
120 must be set to ARCHIVE_COMPONENT_INFO_VERSION_1 by the
121 caller. All other structure elements are output.
122 comp_bc
123 is the bit_count of the archive component.
124 comp_ptr
125 is a pointer to the base of the component.
126 name
127 is the name of the component.
128
129
130 time_modified
131 is a clock reading corresponding to the date/time contents
132 modified of the segment from which this component was most
133 recently updated. This is the value reported in the
134 "modified" column by the "ac tl" command. It may be
135 inaccurate by several hours if the archive was updated in a
136 different time zone from the current time zone.
137 time_updated
138 is a clock reading corresponding to the date/time when this
139 component was last updated in the archive. This is the
140 value reported in the "updated" column by the "ac tl"
141 command. It may be inaccurate by several hours if the
142 archive was updated in a different time zone from the
143 current time zone.
144
145
146 comp_lth
147 is the size, in words, of the component. Both the size in
148 words and the bit_count are provided as a convenience to
149 the caller. The size in words is derived from the
150 bit_count.
151 access
152 is the representation of the effective access mode recorded
153 with the archive component. The first bit is "r" access,
154 the second is "e", and the third is "w". Even if "a"
155 access appears in the archive itself, it will be ignored.
156
157
158 :Entry: next_component: 03/18/81 archive_$next_component
159
160
161 Function: This entry, given a pointer to an archive and its bitcount,
162 and a pointer to the base of a component or null, returns a pointer
163 to the next component in the archive, its name, and its bitcount. If
164 there are no components remaining in the archive, the pointer is
165 returned null on output. The first time this is called for a
166 particular archive, the component pointer should be supplied as null.
167
168
169 Syntax:
170 dcl archive_$next_component entry pointer fixed bin 24 pointer
171 fixed bin 24 char * fixed bin 35;
172 call archive_$next_component archive_ptr archive_bc component_ptr
173 component_bc component_name code;
174
175
176 Arguments:
177 archive_ptr
178 is a pointer to the base of the archive segment to be searched. It
179 need not point to the base of a segment; it is converted to a
180 segment base pointer by archive_, so a pointer to anywhere in the
181 segment may be given here. Input
182 archive_bc
183 is the bitcount of the archive segment. Input
184 component_ptr
185 on input, this is a pointer to the previous component in the
186 archive, or null to indicate that the next component should be the
187 first component in the archive. On output, this is a pointer to the
188 next component in the archive, or null if there are no components
189 remaining after the one it pointed to on input. Input/Output
190
191
192 component_bc
193 is the bitcount of the selected component. Output
194 component_name
195 is the name of the selected component. Output
196 code
197 is a standard system status code, one of the following; Output
198 error_table_$not_archive
199 error_table_$archive_fmt_err
200
201
202 :Entry: next_component_info: 03/18/81 archive_$next_component_info
203
204
205 Function: This entry, given a pointer to an archive, the bitcount of
206 the archive, and a pointer to the base of a component or null,
207 returns a pointer to the next component in the archive and fills in a
208 archive_component_info structure to describe it. If there are no
209 components remaining in the archive, the pointer is returned null on
210 output. The first time this is called for a particular archive, the
211 component pointer should be supplied as null. See also
212 archive_$get_component_info and archive_$next_component.
213
214
215 Syntax:
216 dcl archive_$next_component_info entry pointer fixed bin 24
217 pointer pointer fixed bin 35;
218 call archive_$next_component_info archive_ptr archive_bc
219 component_ptr archive_component_info_ptr code;
220
221
222 Arguments:
223 archive_ptr
224 is a pointer to the base of the archive segment to be searched. It
225 need not point to the base of a segment; it is converted to a
226 segment base pointer by archive_, so a pointer to anywhere in the
227 segment may be given here. Input
228 archive_bc
229 is the bitcount of the archive segment. Input
230 component_name
231 is the name of the component to be searched for. It may be up to
232 32 characters long. Input
233
234
235 archive_component_info_ptr
236 is a pointer to a user-supplied archive_component_info structure,
237 described in the description of the archive_$get_component_info
238 entrypoint. The caller must have previously set
239 archive_component_info.version to the appropriate version number,
240 currently ARCHIVE_COMPONENT_INFO_VERSION_1. The structure is filled
241 in with information describing the selected archive component if
242 component_ptr is returned non-null. Input
243 code
244 is a standard system status code. Output It may be one of the
245 following:
246 error_table_$not_archive
247 error_table_$archive_fmt_err
248 error_table_$unimplemented_version
249
250
251 :Entry: list_components: 03/18/81 archive_$list_components
252
253
254 Function: This entry, given a pointer to an archive and its bitcount,
255 and a pointer to an area, allocates an array of archive_component_info
256 structures in the area to describe all the components in the archive,
257 and returns a pointer to and the size of this array.
258
259
260 Syntax:
261 dcl archive_$list_components entry pointer fixed bin 24 fixed bin
262 pointer pointer fixed bin fixed bin 35;
263 call archive_$list_components archive_ptr archive_bc info_version
264 area_ptr archive_component_info_array_ptr n_components code;
265
266
267 Arguments:
268 archive_ptr
269 is a pointer to the base of the archive segment to be searched. It
270 need not point to the base of a segment; it is converted to a
271 segment base pointer by archive_, so a pointer to anywhere in the
272 segment may be given here. Input
273 archive_bc
274 is the bitcount of the archive segment. Input
275 info_version
276 is the version number for the archive_component_info structure array
277 which will be allocated and returned. The only supported version is
278 ARCHIVE_COMPONENT_INFO_VERSION_1. Input
279
280
281 area_ptr
282 is a pointer to a caller-supplied area in which the returned array
283 of archive_component_infos will be allocated. If area_ptr is null,
284 no list will be allocated, but n_components will still be set; this
285 can be used when it is desired to merely count the components in the
286 archive. Input
287 archive_component_info_array_ptr
288 is a pointer returned which points to an array of
289 archive_component_info structures describing all the components in
290 the archive. It should be declared as follows: Output
291
292 dcl 1 archive_component_info_array n_components aligned
293 like archive_component_info based
294 archive_component_info_array_ptr;
295
296
297 n_components
298 is the number of components in the archive. This may be zero if the
299 archive is empty, and is still valid. Output
300 code
301 is a standard system status code, one of the following; Output
302 error_table_$not_archive
303 error_table_$archive_fmt_err