1 03/15/85  file_manager_
  2 
  3 
  4 The file_manager_ subroutine is the interface between the data storage
  5 and retrieval services of data management and Multics file access and
  6 control mechanisms.  It also ensures concurrency and recovery
  7 protection by invoking data management integrity services when
  8 protected data management (DM) files are accessed or modified.
  9 
 10 As a direct user interface, the file_manager_ subroutine makes the
 11 protection and recovery capabilities of integrity services available to
 12 users who write applications using their own data storage and retrieval
 13 software.
 14 
 15 
 16 Entry points in file_manager_:
 17    (List is generated by the help command)
 18 
 19 
 20 :Entry:  close:  03/15/85 file_manager_$close
 21 
 22 
 23 Function:  This entry point closes a DM file in the current process.
 24 The file to be closed is designated by its opening identifier.
 25 
 26 
 27 Syntax:
 28 declare file_manager_$close entry (bit(36) aligned, fixed bin(35));
 29 call file_manager_$close (oid, code);
 30 
 31 
 32 Arguments:
 33 oid
 34    is the file opening identifier of the file to be closed.
 35    (Input/Output) It is set to zero by this entry point in order to
 36    indicate that it is no longer valid.
 37 code
 38    is a standard status code.  (Output)
 39 
 40 
 41 Notes:  If the file is opened more than once in the process, this
 42 operation decreases the number of openings by one.  See the description
 43 of the open entry for more details.
 44 
 45 The user process does not have to be in transaction mode to close a DM
 46 file.  Aborting a transaction does not cause the file to be reopened,
 47 even if it was closed by a delete_close operation and the deletion was
 48 rolled back.
 49 
 50 
 51 :Entry:  create:  03/15/85 file_manager_$create
 52 
 53 
 54 Function:  This entry point creates a DM file.  The caller specifies
 55 its pathname and attributes, and must specify whether the file is
 56 protected; see "Notes" below.
 57 
 58 
 59 Syntax:
 60 declare file_manager_$create (char(*), char(*), ptr, fixed bin(35));
 61 call file_manager_$create (dir_path, entry_name, file_create_info_ptr,
 62      code);
 63 
 64 
 65 Arguments:
 66 dir_path
 67    is the absolute pathname of a directory.  (Input) The file will be
 68    added to this directory.
 69 entry_name
 70    is the name of the file.  (Input)
 71 file_create_info_ptr
 72    points to the file_create_info structure.  (Input) If
 73    this pointer is null, a protected file is created with the default
 74    attribute values.
 75 code
 76    is a standard status code.  (Output)
 77 
 78 
 79 Access required:
 80 You cannot create a DM file in your home directory unless you have the
 81 proper access to the directory above the containing directory, and, in
 82 any event, you must have sufficient access to add an entry to the
 83 containing directory.  The file is created with read and write access
 84 for the caller and the DM daemon (Data_Management.Daemon).
 85 
 86 
 87 Notes:  In the current implementation, file attributes specified in the
 88 file_create_info structure such as ring brackets and blocking factor
 89 cannot be changed.
 90 
 91 
 92 :Entry:  create_open:  03/15/85 file_manager_$create_open
 93 
 94 
 95 Function:  Calling this entry point has the effect of calling the
 96 create and open entries, but is more efficient.  If the file already
 97 exists, it is opened and code is dm_error_$file_already_exists.  If the
 98 file already exists and is already open, the opening identifier is
 99 returned and code is dm_error_$file_already_open.
100 
101 
102 Syntax:
103 declare file_manager_$create_open entry (char(*), char(*), ptr, bit(36)
104      aligned, fixed bin(35));
105 call file_manager_$create_open (dir_path, entry_name,
106      file_create_info_ptr, oid, code);
107 
108 
109 Arguments:
110 dir_path
111    is the absolute pathname of a directory.  (Input) The file is added
112    to this directory.
113 entry_name
114    is the name of the file.  (Input)
115 file_create_info_ptr
116    is a pointer to a file_create_info structure into which the file
117    attributes are to be placed.  (Input) This structure may in turn be
118    used to create a new DM file into which to copy the old DM file.
119    The structure is defined in dm_fm_create_info.incl.pl1.
120 
121 
122 oid
123    is the opening identifier assigned to the file.  (Output) If it is
124    not zero, the oid is valid and can be used, regardless of the value
125    of code.  If the transaction aborts and the file is deleted, it
126    still needs to be closed, since openings are not undone by rollback.
127 code
128    is a standard status code.  (Output) If it is
129    dm_error_$file_already_exists or dm_error_$file_already_open, the
130    operation is considered successful and oid is usable.
131 
132 
133 :Entry:  delete_close:  03/15/85 file_manager_$delete_close
134 
135 
136 Function:  Calling this entry point has the same effect as calling the
137 delete and close entries, but is more efficient.  It deletes a file
138 that is already open.
139 
140 
141 Syntax:
142 declare file_manager_$delete_close entry (bit(36) aligned, fixed
143      bin(35));
144 call file_manager_$delete_close (oid, code);
145 
146 
147 Arguments:
148 oid
149    is the file opening identifier of the file to be deleted and closed.
150    (Input/Output) It is set to zero by this entry point in order to
151    indicate that it is no longer valid.  The file remains closed even
152    if the transaction is aborted, negating the delete operation.
153 code
154    is a standard status code.  (Output)
155 
156 
157 :Entry:  free:  03/15/85 file_manager_$free
158 
159 
160 Function:  This entry point frees disk space allocated to control
161 intervals.  The set of consecutive control intervals is specified by
162 the number of the first control interval and the number of consecutive
163 control intervals starting at the first one.  After the disk space for
164 a control interval has been freed, its content is effectively zero.
165 This operation has a high fixed overhead, so it should not be called
166 for one control interval at a time.
167 
168 If any or all of the control intervals are already free, code is set to
169 dm_error_$ci_already_free.  The operation is, nevertheless, successful.
170 
171 
172 Syntax:
173 declare file_manager_$free entry (bit(36) aligned, fixed bin(27), fixed
174      bin(27), fixed bin(35));
175 call file_manager_$free (oid, first_ci, n_ci, code);
176 
177 
178 Arguments:
179 oid
180    is a file opening identifier.  (Input)
181 first_ci
182    is the control interval number of the first control interval of the
183    set whose physical space is to be freed.  (Input)
184 n_ci
185    is the number of consecutive control intervals whose physical space
186    is to be freed.  (Input)
187 code
188    is a standard status code.  (Output) If it is
189    dm_error_$ci_already_free, the operation can still be considered a
190    success.
191 
192 
193 Access required:
194 The user must have write access to the file.
195 
196 
197 Notes:  If the file is protected, the caller must be in transaction
198 mode and the free operation is done under the auspices of the integrity
199 services.  If the transaction aborts, the control intervals are
200 reallocated and their contents restored.
201 
202 
203 :Entry:  get:  03/15/85 file_manager_$get
204 
205 
206 Function:  This entry point reads data from a control interval.  The
207 caller may specify one or several parts.  Each part is described by its
208 byte offset relative to the beginning of the addressable portion of the
209 control interval and its length in bytes.  Each part has a pointer to a
210 buffer provided by the caller.
211 
212 If the control interval does not exist, the buffers provided by the
213 caller are filled with zeros and code is set to zero.
214 
215 
216 Syntax:
217 declare file_manager_$get entry (bit(36) aligned, fixed bin(27), ptr,
218      fixed bin(35));
219 call file_manager_$get (oid, ci_num, ci_parts_ptr, code);
220 
221 
222 Arguments:
223 oid
224    is a file opening identifier.  (Input)
225 ci_num
226    is a control interval number.  (Input)
227 ci_parts_ptr
228    points to the ci_parts structure declared in dm_ci_parts.incl.pl1.
229    (Input)
230 code
231    is a standard status code.  (Output)
232 
233 
234 Notes:  If the file is protected, the process must be in transaction
235 mode, and unless no_concurrency is specified, get locks the control
236 interval in share mode.  It is kept locked until the end of the
237 transaction.  This assures that no other transaction can put anything
238 into the control interval, free it, or delete the file during the
239 current transaction.  If the control interval is locked in exclusive
240 mode by another transaction, get waits until it finishes.  If waiting
241 is pointless because the current transaction is deadlocked with another
242 transaction, the transaction_deadlock condition is signaled.
243 
244 
245 Access required:
246 The calling process must have read access to call the get entry.
247 
248 
249 :Entry:  get_ci_header:  03/15/85 file_manager_$get_ci_header
250 
251 
252 Function: This entry reads the 4-word control interval header.  The
253 header tells whether a control interval is allocated when it was last
254 modified, and what the unique identifier of the DM file is.
255 
256 Protection and access are the same as for the get entry.
257 
258 If the control interval does not exist, this entry returns the header
259 that it would have had, with zero in the time_modified field and code
260 set to zero.  It does not create the control interval.
261 
262 
263 Syntax:
264 declare file_manager_$get_ci_header entry (bit(36) aligned, fixed
265      bin(27), 1 like ci_header aligned, fixed bin(35));
266 call file_manager_$get_ci_header (oid, ci_num, ci_header, code);
267 
268 
269 Arguments:
270 oid
271    is a file opening identifier.  (Input)
272 ci_num
273    is a control interval number.  (Input)
274 ci_header
275    is the ci_header structure, declared in dm_ci_header.incl.pl1.
276    (Input/Output)
277 code
278    is a standard status code.  (Output)
279 
280 
281 :Entry:  get_ci_ptr:  03/15/85 file_manager_$get_ci_ptr
282 
283 
284 Function:  This entry point returns a pointer to the addressable
285 portion of a control interval.  Pointers to control intervals should be
286 used only in well defined and contained situations to enhance the
287 performance of accessing data in a control interval for retrieval
288 purposes.  This entry is helpful when it is known beforehand that
289 several pieces of data are to be read from the same control interval,
290 but they cannot be read by specifying several parts to the get entry
291 (e.g., the offset of one is dependent on the value of another).  Unlike
292 other entries which get data, it is not valid to get a control interval
293 pointer to a control interval that is not allocated.
294 
295 
296 Syntax:
297 declare file_manager_$get_ci_ptr entry (bit(36) aligned, fixed bin(27),
298      ptr, fixed bin(35));
299 call file_manager_$get_ci_ptr (oid, ci_num, ci_ptr, code);
300 
301 
302 Arguments:
303 oid
304    is a file opening identifier.  (Input)
305 ci_num
306    is a control interval number.  (Input)
307 ci_ptr
308    points to the addressable portion of the control interval.
309    (Input/Output) The addressable portion begins immediately after the
310    control interval header.  A null value is returned for this pointer
311    if there is a error and the returned code is not zero.
312 code
313    is a standard status code.  (Output) It can be
314    dm_error_$ci_not_allocated if the specified control interval has not
315    been allocated.  ci_ptr is set to null.
316 
317 
318 Notes:  In order to make it possible to look at control intervals via a
319 pointer, the create entry sets the ring brackets on file components to:
320      <DM-ring>,<validation-level>,<validation-level>.
321 If the file is protected, the process must be in transaction mode, and
322 unless no_concurrency is specified, get_ci_ptr locks the control
323 interval in share mode.  It is kept locked until the end of the
324 transaction.  This assures that no other transaction can put anything
325 into the control interval, free it, or delete the file during the
326 current transaction.  If the control interval is locked in exclusive
327 mode by another transaction, get_ci_ptr waits until it finishes.  If
328 waiting is pointless because the current transaction is deadlocked with
329 another transaction, the transaction_deadlock condition is signaled.
330 
331 If the control interval does not exist, an error code of value
332 dm_error_$ci_not_allocated is returned.
333 
334 
335 Access required:
336 The calling process must have read access to call the get_ci_ptr entry.
337 
338 
339 :Entry:  get_exclusive:  03/15/85 file_manager_$get_exclusive
340 
341 
342 Function:  This entry point is the same as get entry except that it
343 locks the control interval exclusively, preventing other transactions
344 from even obtaining the share lock necessary to do a normal get
345 operation.
346 
347 
348 Syntax:
349 declare file_manager_$get_exclusive entry (bit(36) aligned, fixed
350      bin(27), ptr, fixed bin(35));
351 call file_manager_$get_exclusive (oid, ci_num, ci_parts_ptr, code);
352 
353 
354 Arguments:
355 oid
356    is a file opening identifier.  (Input)
357 ci_num
358    is a control interval number.  (Input)
359 ci_parts_ptr
360    points to the ci_parts structure declared in dm_ci_parts.incl.pl1.
361    (Input)
362 code
363    is a standard status code.  (Output)
364 
365 
366 Notes:  This entry is useful for applications that are going to do a
367 put operation into the same control interval.
368 
369 Obtaining an exclusive lock on a control interval effectively reduces
370 concurrency, so this entry should be used advisedly.
371 
372 
373 :Entry:  get_stream:  03/15/85 file_manager_$get_stream
374 
375 
376 Function:  This entry point returns a specified number of bytes from a
377 DM file, given an opening identifier, a file offset, and a buffer in
378 which to place the bytes.  This entry treats the DM file as a stream of
379 bytes consisting of the concatenation of the addressable portion of all
380 control intervals in the DM file.
381 
382 
383 Syntax:
384 declare file_manager_$get_stream entry (bit(36) aligned, fixed bin(48),
385      ptr, fixed bin(21));
386 call file_manager_$get_stream (oid, file_offset_in_bytes, buf_ptr,
387      buf_length_in_bytes);
388 
389 
390 Arguments:
391 oid
392    is the opening identifier of the DM file to be read from.  (Input)
393 file_offset_in_bytes
394    is the offset given in bytes, from the beginning of the logical
395    address space of the DM file given in bytes with an offset of zero
396    representing the beginning of the file.  (Input)
397 buf_ptr
398    is a pointer to a buffer where the bytes read from the DM file may
399    be placed.  (Input)
400 buf_length_in_bytes
401    is the number of bytes that are to be read from the DM file.
402    (Input)
403 
404 
405 Notes:  If the DM file is protected, the process must be in transaction
406 mode and unless concurrency is specified, get_stream locks in share
407 mode the control intervals in which the specified stream of bytes
408 resides.
409 
410 
411 Access required:
412 The calling process must have read access to the DM file to call the
413 get_stream entry.
414 
415 
416 :Entry:  lock_advice:  03/15/85 file_manager_$lock_advice
417 
418 
419 Function:  This entry point permits applications to give the file
420 manager advice about locking granularity.  For example, if an
421 application is to modify every control interval in a file, it can
422 request the file manager to lock the entire file and save the overhead
423 of locking individual control intervals.
424 
425 
426 Syntax:
427 declare file_manager_$lock_advice entry (bit(36) aligned, fixed bin,
428      fixed bin(35));
429 call file_manager_$lock_advice (oid, lock_mode, code);
430 
431 
432 Arguments:
433 oid
434    is a file opening identifier.  (Input)
435 lock_mode
436    is the finest and weakest lock mode to use on this file for the
437    remainder of the opening.  (Input) It must be one of the five
438    following modes:  4 (LOCK_MODE_IS), 5 (LOCK_MODE_IX), 6
439    (LOCK_MODE_SIX), 2 (LOCK_MODE_S), or 3 (LOCK_MODE_X) which are
440    declared in dm_lock_modes.incl.pl1.
441 code
442    is a standard status code.  (Output)
443 
444 
445 Notes:  Lock advice never abridges protection against concurrent file
446 access by other processes.  If no lock advice is given, file manager
447 uses the weakest lock necessary to provide concurrency protection, and
448 the finest granularity available, which is the control interval.  Lock
449 advice always causes file manager to use a stronger lock or coarser
450 granularity than absolutely necessary.  This reduces concurrency in
451 order to reduce locking overhead.
452 
453 Lock advice applies to protected files unless the no_concurrency
454 attribute is present.  Since it is an attribute of the opening and not
455 of the file, it can be given to any open file, regardless of whether a
456 transaction is in progress.  The first time the file is referenced in
457 each transaction, the advice tells the file manager what kind of a
458 global file lock to acquire.  If the lock advice is given after the
459 first time the file is referenced, it will not be used until the next
460 transaction.  The lock advice is retained until it is changed, or the
461 file is closed.
462 
463 
464 The advice concerns the type of lock to use at the file level.  The
465 only way to control the type of lock used on a control interval is to
466 call get_exclusive instead of get.  If no advice is given, IS
467 (intention shared) is presumed.  IS is strong enough for get and
468 get_ci_header which lock control intervals in S (share) mode.  Put,
469 allocate, and free require that the file lock be upgraded to the
470 stronger IX (intention exclusive) mode, because they lock control
471 intervals in X (exclusive) mode.  Create and delete lock the file in X
472 mode, regardless.  If advice is given, then all operations lock the
473 file in the advised mode unless it is too weak for the operation.  The
474 SIX (shared and intention exclusive) mode means only lock the control
475 intervals that are modified.  SIX saves the overhead of locking
476 individual control intervals for get operations because it prevents
477 other transactions from getting anything but an IS lock on the file.
478 
479 
480 :Entry:  open:  03/15/85 file_manager_$open
481 
482 
483 Function:  This entry point makes a DM file accessible within a
484 process.  The file is specified by its pathname.  The file is assigned
485 an opening identifier in the current process, by which it is designated
486 in all subsequent calls to file_manager_.
487 
488 
489 Syntax:
490 declare file_manager_$open entry (char(*), char(*), bit(36) aligned,
491      fixed bin(35));
492 call file_manager_$open (dir_path, entry_name, oid, code);
493 
494 
495 Arguments:
496 dir_path
497    is the absolute pathname of the directory which contains the file.
498    (Input)
499 entry_name
500    is the entry name of the file.  (Input)
501 oid
502    is the file opening identifier assigned to the file and returned to
503    the caller.  (Output) If it is not zero, it is usable, regardless of
504    code.
505 code
506    is a standard status code.  (Output) If it is
507    dm_error_$file_already_open, the operation is considered successful
508    and oid is usable.
509 
510 
511 Notes:  If the file was already opened in the current process, the open
512 entry does not assign a new opening identifier, but rather returns the
513 opening identifier that was already assigned and sets code to
514 dm_error_$file_already_open.  The file manager keeps track of the
515 number of opens and closes.  The opening identifier remains valid as
516 long as there are more opens than closes.  If all subsystems within a
517 process close a file the same number of times they open it, they will
518 not invalidate each others openings.
519 
520 There is no requirement for the process to be in transaction mode when
521 opening a file, protected or not.  Aborting a transaction has no effect
522 on file openings, even if create_open was called and the create is
523 rolled back.  Attempts to use such an opening will result in
524 dm_error_$file_doesnt_exist.  The same thing happens if a file is
525 opened and then deleted.  Close is the only operation allowed on a file
526 which has been deleted.
527 
528 
529 :Entry:  put:  03/15/85 file_manager_$put
530 
531 
532 Function:  This entry point writes data into a control interval.  The
533 caller can specify one or several parts of the control interval to be
534 written.
535 
536 If the control interval does not exist, it is automatically allocated
537 and the content of its addressable portion is initialized to zero.
538 
539 
540 Syntax:
541 declare file_manager_$put entry (bit(36) aligned, fixed bin(27), ptr,
542      fixed bin(35));
543 call file_manager$put (oid, ci_num, ci_parts_ptr, code);
544 
545 
546 Arguments:
547 oid
548    is a file opening identifier.  (Input)
549 ci_num
550    is a control interval number.  (Input)
551 ci_parts_ptr
552    points to the ci_parts structure declared in dm_ci_parts.incl.pl1.
553    (Input)
554 code
555    is a standard status code.  (Output)
556 
557 
558 Notes:  If the file is protected, the process must be in transaction
559 mode, and unless no_concurrency is specified, put locks the control
560 interval in exclusive mode.  It is kept locked until the end of the
561 transaction.  This assures that no other transaction can put anything
562 into the control interval, get anything from it, free it, or delete the
563 file during the current transaction.  If the control interval is locked
564 by another transaction, the put operation must wait until it finishes.
565 If waiting is pointless because the current transaction is deadlocked
566 with another transaction, the transaction_deadlock condition is
567 signaled.
568 
569 Unless the file is unprotected or has the no_rollback attribute, a put
570 operation causes a before image of data in the control interval to be
571 journalized before actually modifying it.  If the transaction should
572 abort, the before journal manager will undo its modifications by
573 restoring the before images.
574 
575 
576 The modified control interval can not be written to disk until its
577 before image is on disk, because there must be enough information on
578 disk to roll back the transaction even if main memory fails.  If the
579 modified control interval were written first and the system failed
580 before the transaction finished and the content of main memory could
581 not be flushed to disk, the modification could not be undone and
582 rollback of the transaction would be incomplete.  The data management
583 system holds modified control intervals in main memory until the
584 associated before images are written to disk.  The Multics clock value
585 in the control interval header is used for this purpose.
586 
587 
588 The put request is rejected if either of the following is true:
589 
590    - The user does not have write permission on the file.
591    - The file is protected but the process is not in a transaction
592      mode.
593 
594 
595 :Entry:  put_stream:  03/15/85 file_manager_$put_stream
596 
597 
598 Function:  This entry point writes a specified number of bytes in a DM
599 file at a given offset in the logical address space.  This entry treats
600 the DM file as a stream of bytes made up of the concatenation of the
601 addressable portion of all control intervals in the DM file.
602 
603 
604 Syntax:
605 declare file_manager_$put_stream entry (bit(36) aligned, fixed bin(48),
606      ptr, fixed bin(21), fixed bin(35));
607 call file_manager_$put (oid, file_offset_in_bytes, buf_ptr,
608      buf_length_in_bytes, code);
609 
610 
611 Arguments:
612 oid
613    is the opening identifier of the DM file.  (Input)
614 file_offset_in_bytes
615    is the offset in bytes into the logical address space of the DM file
616    where the supplied bytes will be placed.  (Input)
617 buf_ptr
618    is a pointer to the buffer containing the bytes to be written to the
619    DM file.  (Input)
620 buf_length_in_bytes
621    is the number of bytes to be written into the DM file from the
622    buffer.  (Input)
623 code
624    is a standard system status code.  (Input)
625 
626 
627 Notes:  If the DM file is protected, the process must be in transaction
628 mode, and unless concurrency is specified, put_stream locks the control
629 intervals in which the specified stream of bytes resides.
630 
631 
632 Access required:
633 The calling process must have write access to the DM file to call the
634 put_stream entry.
635 
636 
637 :Entry:  raw_get:  03/15/85 file_manager_$raw_get
638 
639 
640 Function:  This entry point resembles the get entry, except that it
641 treats the file as if it were unprotected.  It does not require that
642 the process be in transaction mode.
643 
644 
645 Syntax:
646 declare file_manager_$raw_get entry (bit(36) aligned, fixed bin(27),
647      ptr, fixed bin(35));
648 call file_manager_$raw_get (oid, ci_num, ci_parts_ptr, code);
649 
650 
651 Arguments:
652 oid
653    is a file opening identifier.  (Input)
654 ci_num
655    is a control interval number.  (Input)
656 ci_parts_ptr
657    points to a ci_parts structure declared in dm_ci_parts.incl.pl1.
658    (Input)
659 code
660    is a standard status code.  (Output)
661 
662 
663 :Entry:  raw_put:  03/15/85 file_manager_$raw_put
664 
665 
666 Function:  This entry point resembles the put entry, except that it
667 treats the file as if it were unprotected.  Also, the time_modified
668 stamp in the control interval header is not updated.  This operation is
669 intended for applications that need to update protected files in an
670 unprotected manner.  It does not require that the process be in
671 transaction mode.
672 
673 
674 Syntax:
675 declare file_manager_$raw_put entry (bit(36) aligned, fixed bin(27),
676      ptr, fixed bin(35));
677 call file_manager_$raw_put (oid, ci_num, ci_parts_ptr, code);
678 
679 
680 Arguments:
681 oid
682    is a file opening identifier.  (Input)
683 ci_num
684    is a control interval number.  (Input)
685 ci_parts_ptr
686    points to a ci_parts structure declared in dm_ci_parts.incl.pl1.
687    (Input)
688 code
689    is a standard status code.  (Output)
690 
691 
692 :Entry:  simple_get:  03/15/85 file_manager_$simple_get
693 
694 
695 Function:  This entry point is used to get a sequence of bytes from a
696 DM file, given an opening identifier, a control interval number, and
697 control interval offset.  The sequence is placed in a caller-supplied
698 buffer.  This entry point differs from the get entry in that it can
699 only get bytes from one location within a control interval, and a
700 ci_parts structure does not have to exist to make the call.
701 
702 
703 Syntax:
704 declare file_manager_$simple_get entry (bit(36) aligned, fixed bin(27),
705      fixed bin(21), ptr, fixed bin(21));
706 call file_manager_$simple_get (oid, ci_num, ci_offset_in_bytes,
707      buf_ptr, buf_length_in_bytes);
708 
709 
710 Arguments:
711 oid
712    is the opening identifier of the DM file.  (Input)
713 ci_num
714    is the control interval in the DM file that contains the data to be
715    fetched.  (Input)
716 ci_offset_in_bytes
717    is the offset from the beginning of the control interval to the
718    beginning of the data, expressed in bytes.  (Input)
719 buf_ptr
720    is a pointer to a caller supplied buffer where the data is to be
721    placed.  (Input)
722 
723 
724 buf_length_in_bytes
725    is the length in bytes of the caller supplied buffer.  (Input) This
726    also specifies the number of bytes to be fetched.  The sum of
727    ci_offset_in_bytes and buf_length_in_bytes must not exceed the
728    length of a control interval.
729 code
730    is a standard system status code.  (Output)
731 
732 
733 :Entry:  simple_put:  03/15/85 file_manager_$simple_put
734 
735 
736 Function:  This entry point places a given sequence of bytes into a DM
737 file, given an open id, a control interval number, and a control
738 interval offset.  This entry differs from the put entry point in that
739 it places bytes only at one given location within a control interval,
740 so no ci_parts structure is required.
741 
742 
743 Syntax:
744 declare file_manager_$simple_put entry (bit(36) aligned, fixed bin(27),
745      fixed bin(21), ptr, fixed bin(21));
746 call file_manager_$simple_put (oid, ci_num, ci_offset_in_bytes,
747      buf_ptr, buf_length_in_bytes);
748 
749 
750 Arguments:
751 oid
752    is the opening identifier of the DM file.  (Input)
753 ci_num
754    is the control interval in the DM file where the data is to be
755    placed.  (Input)
756 ci_offset_in_bytes
757    is the offset from the beginning of the control interval to the
758    beginning of where the data is to be placed.  (Input)
759 buf_ptr
760    is a pointer to the buffer containing the data.  (Input)
761 buf_length_in_bytes
762    is the number of bytes that are to be placed into the DM file.
763    (Input)
764 code
765    is a standard system status code.  (Output)
766 
767 
768 :Entry:  status:  03/15/85 file_manager_$status
769 
770 
771 Function:  This entry point returns status information on a DM file.
772 
773 
774 Syntax:
775 declare file_manager_$status entry (bit(36), ptr, fixed bin(35));
776 call file_manager_$status (oid, file_status_ptr, code);
777 
778 
779 Arguments:
780 oid
781    is the opening identifier of the DM file.  (Input)
782 file_status_ptr
783    is a pointer to a file_status structure to be filled in by this
784    entry.  (Input) See the include file dm_file_status.incl.pl1.
785 code
786    is a standard system status code.  (Output)
787 
788 
789 Notes:
790 The structure that lists the information returned by
791 file_manager_$status to describe a DM file is declared in
792 dm_file_status.incl.pl1.
793 
794 
795 :Entry:  terminate_ci_ptr:  03/15/85 file_manager_$terminate_ci_ptr
796 
797 
798 Function:  This entry point releases a control interval pointer to a
799 specific control interval of a DM file retrieved through the get_ci_ptr
800 entry point.  This entry must be called for each call to get_ci_ptr.
801 
802 
803 Syntax:
804 declare file_manager_$terminate_ci_ptr entry (bit(36) aligned, fixed
805      bin(27), ptr, fixed bin(35));
806 call file_manager_$terminate_ci_ptr (oid, ci_num, ci_ptr, code);
807 
808 
809 Arguments:
810 oid
811    is the opening identifier of the DM file.  (Input)
812 ci_num
813    is the number of the control interval that ci_ptr points to.
814    (Input)
815 ci_ptr
816    is the control interval pointer to be terminated.  (Input)
817 code
818    is a standard system status code.  (Output)