1 03/19/84  msf_manager_
  2 
  3 The msf_manager_ subroutine provides a centralized and consistent
  4 facility for handling multisegment files.  Multisegment files are files
  5 that can require more than one segment for storage.  Examples of
  6 multisegment files are listings, data used through I/O switches, and
  7 APL workspaces.  The msf_manager_ subroutine makes multisegment files
  8 almost as easy to use as single segment files in many applications.
  9 
 10 A multisegment file is composed of one or more components, each the
 11 size of a segment, identified by consecutive unsigned integers.  Any
 12 word in a single segment file can be specified by a pathname and a word
 13 offset.  Any word in a multisegment file can be specified by a
 14 pathname, component number, and word offset within the component.  The
 15 msf_manager_ subroutine provides the means for creating, accessing, and
 16 deleting components, truncating the multisegment file, and controlling
 17 access.
 18 
 19 
 20 In this implementation, a multisegment file with only component 0 is
 21 stored as a single segment file, unless the msf_manager_$msf_get_ptr
 22 entrypoint was responsible for creating the file, in which case it is
 23 stored as a multisegment file with only one component.  If components
 24 other than 0 are present, they are stored as segments with names
 25 corresponding to the ASCII representation of their component numbers in
 26 a directory with the pathname of the multisegment file.
 27 
 28 
 29 The ACL of the multisegment file is maintained on each component of the
 30 multisegment file.  This ACL is translated into a similar directory ACL
 31 maintained on the directory portion of the multisegment file.  The
 32 directory ACL is maintained such that all users have at least "s"
 33 access to the directory portion so that all users can determine their
 34 actual access mode to the multisegment file.
 35 
 36 
 37 
 38 To keep information between calls, the msf_manager_ subroutine stores
 39 information about files in per-process data structures called file
 40 control blocks.  The user is returned a pointer to a file control block
 41 by the entry point msf_manager_$open.  This pointer, fcb_ptr, is the
 42 caller's means of identifying the multisegment file to the other
 43 msf_manager_ entry points.  The file control block is freed by the
 44 msf_manager_$close entry point.
 45 
 46 
 47 Entry points in msf_manager_:
 48    (List is generated by the help command)
 49 
 50 
 51 :Entry:  acl_add:  03/19/84 msf_manager_$acl_add
 52 
 53 
 54 Function:  This entry point adds the specified access modes to the ACL
 55 of the multisegment file.
 56 
 57 
 58 Syntax:
 59 declare msf_manager_$acl_add entry (ptr, ptr, fixed bin,
 60      fixed bin(35));
 61 call msf_manager_$acl_add (fcb_ptr, acl_ptr, acl_count, code);
 62 
 63 
 64 Arguments:
 65 fcb_ptr
 66    is a pointer to the file control block.  (Input)
 67 acl_ptr
 68    points to the user-supplied segment_acl_array structure declared in
 69    acl_structures.incl.pl1.  (Input)
 70 acl_count
 71    is the number of ACL entries in the segment_acl_array structure.
 72    (Input)
 73 code
 74    is a storage system status code.  (Output) It can be:
 75    error_table_$argerr
 76       the erroneous ACL entries in the segment_acl_array structure have
 77       status_code set to an appropriate error code.  No processing is
 78       performed.
 79 
 80 
 81 List of structure elements:
 82    access_name
 83       is the access name (in the form Person_id.Project_id.tag) that
 84       identifies the process to which this ACL entry applies.
 85 
 86 
 87    modes
 88       contains the modes for this access name.  The first three bits
 89       correspond to the modes read, execute, and write.  The remaining
 90       bits must be 0's.  For example, rw access is expressed as "101"b.
 91       The include file access_mode_values.incl.pl1 defines mnemonics
 92       for these values:
 93 
 94          dcl (N_ACCESS               init ("000"b),
 95               R_ACCESS               init ("100"b),
 96               E_ACCESS               init ("010"b),
 97               W_ACCESS               init ("001"b),
 98               RE_ACCESS              init ("110"b),
 99               REW_ACCESS             init ("111"b),
100               RW_ACCESS              init ("101"b)),
101            bit (3) internal static options (constant);
102 
103 
104    zero_pad
105       must contain the value zero.  (This field is for use with
106       extended access and may only be used by the system.)
107    status_code
108       is a storage system status code for this ACL entry only.
109 
110 
111 :Entry:  acl_delete:  03/19/84 msf_manager_$acl_delete
112 
113 
114 Function:  This entry point deletes ACL entries from the ACL of a
115 multisegment file.
116 
117 
118 Syntax:
119 declare msf_manager_$acl_delete entry (ptr, ptr, fixed bin,
120      fixed bin(35));
121 call msf_manager_$acl_delete (fcb_ptr, acl_ptr, acl_count, code);
122 
123 
124 Arguments:
125 fcb_ptr
126    is a pointer to the file control block.  (Input)
127 acl_ptr
128    points to a user-supplied delete_acl structure which is declared in
129    acl_structures.incl.pl1.  (Input)
130 acl_count
131    is the number of ACL entries in the delete_acl structure.  (Input)
132 code
133    is a storage system status code.  (Output)
134 
135 
136 List of structure elements:
137    access_name
138       is the access name (in the form Person_id.Project_id.tag) of an
139       ACL entry to be deleted.
140    status_code
141       is a storage system status code for this ACL entry only.
142 
143 
144 Notes:  If code is error_table_$argerr, no processing is performed and
145 status_code in each erroneous ACL entry is set to an appropriate error
146 code.
147 
148 If an access name matches no name already on the ACL, then the
149 status_code for that delete_acl entry is set to
150 error_table_$user_not_found.  Processing continues to the end of the
151 delete_acl structure and code is returned as 0.
152 
153 
154 :Entry:  acl_list:  03/19/84 msf_manager_$acl_list
155 
156 
157 Function:  This entry point returns the access control list (ACL) of a
158 multisegment file.
159 
160 
161 Syntax:
162 declare msf_manager_$acl_list entry (ptr, ptr, ptr, ptr, fixed bin,
163      fixed bin(35));
164 call msf_manager_$acl_list (fcb_ptr, area_ptr, area_ret_ptr, acl_ptr,
165      acl_count, code);
166 
167 
168 Arguments:
169 fcb_ptr
170    is a pointer to the file control block.  (Input)
171 area_ptr
172    points to an area in which the list of ACL entries, which make up
173    the entire ACL of the multisegment file, is allocated.  If area_ptr
174    is null, then the user wants access modes for certain ACL entries;
175    these will be specified by the structure pointed to by acl_ptr.
176    (Input)
177 area_ret_ptr
178    points to the start of the allocated list of ACL entries.  (Output)
179 
180 
181 acl_ptr
182    if area_ptr is null, then acl_ptr points to an ACL structure,
183    segment_acl_array, (described in the msf_manager_$acl_add entry
184    point above) into which mode information is placed for the access
185    names specified in that same structure.  (Input)
186 acl_count
187    is the number of entries in the segment_acl_array structure.
188    (Input/Output)
189    Input   is the number of entries in the ACL structure identified
190            by acl_ptr.
191    Output  is the number of entries in the segment_acl_array structure
192            allocated in the area pointed to by area_ptr, if area_ptr
193            is not null.
194 code
195    is a storage system status code.  (Output)
196 
197 
198 Notes:  If acl_ptr is used to obtain modes for specified access names
199 (rather than obtaining modes for all access names in area_ret_ptr),
200 then each ACL entry in the segment_acl_array structure either has
201 status_code set to 0 and contains the multisegment mode of the file or
202 has status_code set to error_table_$user_not_found and contains a mode
203 of 0.
204 
205 
206 :Entry:  acl_replace:  03/19/84 msf_manager_$acl_replace
207 
208 
209 Function:  This entry point replaces the ACL of a multisegment file.
210 
211 
212 Syntax:
213 declare msf_manager_$acl_replace entry (ptr, ptr, fixed bin, bit(1),
214      fixed bin(35));
215 call msf_manager_$acl_replace (fcb_ptr, acl_ptr, acl_count,
216      no_sysdaemon_sw code);
217 
218 
219 Arguments:
220 fcb_ptr
221    is a pointer to the file control block.  (Input)
222 acl_ptr
223    points to the user-supplied segment_acl_array structure (described
224    in the msf_manager_$acl_add entry point above) that is to replace
225    the current ACL.  (Input)
226 acl_count
227    is the number of entries in the segment_acl_array structure.
228    (Input)
229 
230 
231 no_sysdaemon_sw
232    is a switch that indicates whether an rw *.SysDaemon.* entry is to
233    be put on the ACL of the multisegment file after the existing ACL
234    has been deleted and before the user-supplied segment_acl_array
235    entries are added.  (Input)
236    "0"b adds rw *.SysDaemon.* entry.
237    "1"b replaces the existing ACL with only the user-supplied
238       segment_acl_array.
239 code
240    is a storage system status code.  (Output)
241 
242 
243 Notes:  If acl_count is zero, the existing ACL is deleted and only the
244 action indicated (if any) by the no_sysdaemon_sw switch is performed.
245 If acl_count is greater than zero, processing of the segment_acl_array
246 entries is performed top to bottom, allowing a later entry to overwrite
247 a previous one if the access_name in the segment_acl_array structure is
248 identical.
249 
250 
251 :Entry:  adjust:  09/23/86 msf_manager_$adjust
252 
253 
254 Function: The msf_manager_$adjust entry point optionally sets the bit
255 count, truncates, and terminates the components of a multisegment file.
256 The number of the last component and its bit count must be given.  The
257 bit counts of all components but the last are set to the first
258 component's max_length*36.  All components with numbers greater than
259 the given component are deleted.  All components that have been
260 initiated are terminated.  A 3-bit switch is used to control these
261 actions.
262 
263 
264 Syntax:
265 declare msf_manager_$adjust entry (ptr, fixed bin, fixed bin(24),
266      bit(3), fixed bin(35));
267 call msf_manager_$adjust (fcb_ptr, component, bc, switch, code);
268 
269 
270 Arguments:
271 fcb_ptr
272    is a pointer to the file control block.  (Input)
273 component
274    is the number of the last component.  (Input)
275 bc
276    is the bit count to be placed on the last component.  (Input)
277 switch
278    is a 3-bit count/truncate/terminate switch.  (Input)
279    bit count
280       "0"b do not set the bit count.
281       "1"b set the bit count.
282 
283 
284    truncate
285       "0"b do not truncate the given component.
286       "1"b truncate the given component to the length specified in the
287       bc argument.
288    terminate
289       "0"b do not terminate the component.
290       "1"b terminate the component.
291 code
292    is a storage system status code.  (Output)
293 
294 
295 :Entry:  close:  03/19/84 msf_manager_$close
296 
297 
298 Function:  This entry point terminates all components that the file
299 control block indicates are initiated and frees the file control block.
300 
301 
302 Syntax:
303 declare msf_manager_$close entry (ptr);
304 call msf_manager_$close (fcb_ptr);
305 
306 
307 Arguments:
308 fcb_ptr
309    is the pointer to the file control block.
310 
311 
312 :Entry:  get_ptr:  03/19/84 msf_manager_$get_ptr
313 
314 
315 Function:  This entry point returns a pointer to a specified component
316 in the multisegment file.  The component can be created if it does not
317 exist.  If the file is a single segment file, and a component greater
318 than 0 is requested, the single segment is converted to a component 0.
319 (See also the msf_manager_$msf_get_ptr entry point.)
320 
321 
322 Syntax:
323 declare msf_manager_$get_ptr entry (ptr, fixed bin, bit(1), ptr,
324      fixed bin(24), fixed bin(35));
325 call msf_manager_$get_ptr (fcb_ptr, component, create_sw, seg_ptr, bc,
326      code);
327 
328 
329 Arguments:
330 fcb_ptr
331    is a pointer to the file control block.  (Input)
332 component
333    is the number of the component desired.  (Input)
334 create_sw
335    is the create switch.  (Input)
336    "1"b create the component if it does not exist.
337    "0"b do not create the component if it does not exist.
338 seg_ptr
339    is a pointer to the specified component in the file, or null (if
340    there is an error).  (Output)
341 
342 
343 bc
344    is the bit count of the component.  (Output)
345 code
346    is a storage system status code.  (Output) It can be:
347    error_table_$noentry
348       if the component requested did not exist and create_sw is off.
349 
350 
351 :Entry:  msf_get_ptr:  03/19/84 msf_manager_$msf_get_ptr
352 
353 
354 Function:  This entry point returns a pointer to a specified component
355 in the multisegment file.  The component can be created if it does not
356 exist.  If the file is a single segment file, and the requested
357 component is not component 0, the single segment is converted to a
358 multisegment file.  This change does not affect a previously returned
359 pointer to component 0.  If the file does not exist, it is created as a
360 "multi-segment file" with a single component.  This entry point never
361 creates a single segment file.  (See also the msf_manager_$get_ptr
362 entrypoint.)
363 
364 
365 Syntax:
366 declare msf_manager_$msf_get_ptr entry (ptr, fixed bin, bit(1), ptr,
367      fixed bin(24), fixed bin(35));
368 call msf_manager_$msf_get_ptr (fcb_ptr, component, create_sw, seg_ptr,
369      bc, code);
370 
371 
372 Arguments:
373 fcb_ptr
374    is a pointer to the file control block.  (Input)
375 component
376    is the number of the component desired.  (Input)
377 create_sw
378    is the create switch.  (Input)
379    "1"b create the component if it does not exist.
380    "0"b do not create the component if it does not exist.
381 seg_ptr
382    is a pointer to the specified component in the file, or null (if
383    there is an error).  (Output)
384 
385 
386 bc
387    is the bit count of the component.  (Output)
388 code
389    is a storage system status code.  (Output) It can be:
390    error_table_$noentry
391       if the component requested did not exist and create_sw is off.
392 
393 
394 :Entry:  open:  03/19/84 msf_manager_$open
395 
396 
397 Function:  The msf_manager_$open entry point creates a file control
398 block and returns a pointer to it.  The file need not exist for a file
399 control block to be created for it.
400 
401 
402 Syntax:
403 declare msf_manager_$open entry (char(*), char(*), ptr, fixed bin(35));
404 call msf_manager_$open (dir_name, entryname, fcb_ptr, code);
405 
406 
407 Arguments:
408 dir_name
409    is the pathname of the containing directory.  (Input)
410 entryname
411    is the entryname of the multisegment file.  (Input)
412 fcb_ptr
413    is a pointer to the file control block.  (Output)
414 code
415    is a storage system status code.  The code error_table_$dirseg is
416    returned when an attempt is made to open a directory.  (Output)
417 
418 
419 Notes:  If the file does not exist, fcb_ptr is nonnull and the code
420 error_table_$noentry is returned.  If the file cannot be opened,
421 fcb_ptr is null and the value of code returned indicates the reason for
422 failure.