03/19/84 msf_manager_ The msf_manager_ subroutine provides a centralized and consistent facility for handling multisegment files. Multisegment files are files that can require more than one segment for storage. Examples of multisegment files are listings, data used through I/O switches, and APL workspaces. The msf_manager_ subroutine makes multisegment files almost as easy to use as single segment files in many applications. A multisegment file is composed of one or more components, each the size of a segment, identified by consecutive unsigned integers. Any word in a single segment file can be specified by a pathname and a word offset. Any word in a multisegment file can be specified by a pathname, component number, and word offset within the component. The msf_manager_ subroutine provides the means for creating, accessing, and deleting components, truncating the multisegment file, and controlling access. In this implementation, a multisegment file with only component 0 is stored as a single segment file, unless the msf_manager_$msf_get_ptr entrypoint was responsible for creating the file, in which case it is stored as a multisegment file with only one component. If components other than 0 are present, they are stored as segments with names corresponding to the ASCII representation of their component numbers in a directory with the pathname of the multisegment file. The ACL of the multisegment file is maintained on each component of the multisegment file. This ACL is translated into a similar directory ACL maintained on the directory portion of the multisegment file. The directory ACL is maintained such that all users have at least "s" access to the directory portion so that all users can determine their actual access mode to the multisegment file. To keep information between calls, the msf_manager_ subroutine stores information about files in per-process data structures called file control blocks. The user is returned a pointer to a file control block by the entry point msf_manager_$open. This pointer, fcb_ptr, is the caller's means of identifying the multisegment file to the other msf_manager_ entry points. The file control block is freed by the msf_manager_$close entry point. Entry points in msf_manager_: (List is generated by the help command) :Entry: acl_add: 03/19/84 msf_manager_$acl_add Function: This entry point adds the specified access modes to the ACL of the multisegment file. Syntax: declare msf_manager_$acl_add entry (ptr, ptr, fixed bin, fixed bin(35)); call msf_manager_$acl_add (fcb_ptr, acl_ptr, acl_count, code); Arguments: fcb_ptr is a pointer to the file control block. (Input) acl_ptr points to the user-supplied segment_acl_array structure declared in acl_structures.incl.pl1. (Input) acl_count is the number of ACL entries in the segment_acl_array structure. (Input) code is a storage system status code. (Output) It can be: error_table_$argerr the erroneous ACL entries in the segment_acl_array structure have status_code set to an appropriate error code. No processing is performed. List of structure elements: access_name is the access name (in the form Person_id.Project_id.tag) that identifies the process to which this ACL entry applies. modes contains the modes for this access name. The first three bits correspond to the modes read, execute, and write. The remaining bits must be 0's. For example, rw access is expressed as "101"b. The include file access_mode_values.incl.pl1 defines mnemonics for these values: dcl (N_ACCESS init ("000"b), R_ACCESS init ("100"b), E_ACCESS init ("010"b), W_ACCESS init ("001"b), RE_ACCESS init ("110"b), REW_ACCESS init ("111"b), RW_ACCESS init ("101"b)), bit (3) internal static options (constant); zero_pad must contain the value zero. (This field is for use with extended access and may only be used by the system.) status_code is a storage system status code for this ACL entry only. :Entry: acl_delete: 03/19/84 msf_manager_$acl_delete Function: This entry point deletes ACL entries from the ACL of a multisegment file. Syntax: declare msf_manager_$acl_delete entry (ptr, ptr, fixed bin, fixed bin(35)); call msf_manager_$acl_delete (fcb_ptr, acl_ptr, acl_count, code); Arguments: fcb_ptr is a pointer to the file control block. (Input) acl_ptr points to a user-supplied delete_acl structure which is declared in acl_structures.incl.pl1. (Input) acl_count is the number of ACL entries in the delete_acl structure. (Input) code is a storage system status code. (Output) List of structure elements: access_name is the access name (in the form Person_id.Project_id.tag) of an ACL entry to be deleted. status_code is a storage system status code for this ACL entry only. Notes: If code is error_table_$argerr, no processing is performed and status_code in each erroneous ACL entry is set to an appropriate error code. If an access name matches no name already on the ACL, then the status_code for that delete_acl entry is set to error_table_$user_not_found. Processing continues to the end of the delete_acl structure and code is returned as 0. :Entry: acl_list: 03/19/84 msf_manager_$acl_list Function: This entry point returns the access control list (ACL) of a multisegment file. Syntax: declare msf_manager_$acl_list entry (ptr, ptr, ptr, ptr, fixed bin, fixed bin(35)); call msf_manager_$acl_list (fcb_ptr, area_ptr, area_ret_ptr, acl_ptr, acl_count, code); Arguments: fcb_ptr is a pointer to the file control block. (Input) area_ptr points to an area in which the list of ACL entries, which make up the entire ACL of the multisegment file, is allocated. If area_ptr is null, then the user wants access modes for certain ACL entries; these will be specified by the structure pointed to by acl_ptr. (Input) area_ret_ptr points to the start of the allocated list of ACL entries. (Output) acl_ptr if area_ptr is null, then acl_ptr points to an ACL structure, segment_acl_array, (described in the msf_manager_$acl_add entry point above) into which mode information is placed for the access names specified in that same structure. (Input) acl_count is the number of entries in the segment_acl_array structure. (Input/Output) Input is the number of entries in the ACL structure identified by acl_ptr. Output is the number of entries in the segment_acl_array structure allocated in the area pointed to by area_ptr, if area_ptr is not null. code is a storage system status code. (Output) Notes: If acl_ptr is used to obtain modes for specified access names (rather than obtaining modes for all access names in area_ret_ptr), then each ACL entry in the segment_acl_array structure either has status_code set to 0 and contains the multisegment mode of the file or has status_code set to error_table_$user_not_found and contains a mode of 0. :Entry: acl_replace: 03/19/84 msf_manager_$acl_replace Function: This entry point replaces the ACL of a multisegment file. Syntax: declare msf_manager_$acl_replace entry (ptr, ptr, fixed bin, bit(1), fixed bin(35)); call msf_manager_$acl_replace (fcb_ptr, acl_ptr, acl_count, no_sysdaemon_sw code); Arguments: fcb_ptr is a pointer to the file control block. (Input) acl_ptr points to the user-supplied segment_acl_array structure (described in the msf_manager_$acl_add entry point above) that is to replace the current ACL. (Input) acl_count is the number of entries in the segment_acl_array structure. (Input) no_sysdaemon_sw is a switch that indicates whether an rw *.SysDaemon.* entry is to be put on the ACL of the multisegment file after the existing ACL has been deleted and before the user-supplied segment_acl_array entries are added. (Input) "0"b adds rw *.SysDaemon.* entry. "1"b replaces the existing ACL with only the user-supplied segment_acl_array. code is a storage system status code. (Output) Notes: If acl_count is zero, the existing ACL is deleted and only the action indicated (if any) by the no_sysdaemon_sw switch is performed. If acl_count is greater than zero, processing of the segment_acl_array entries is performed top to bottom, allowing a later entry to overwrite a previous one if the access_name in the segment_acl_array structure is identical. :Entry: adjust: 09/23/86 msf_manager_$adjust Function: The msf_manager_$adjust entry point optionally sets the bit count, truncates, and terminates the components of a multisegment file. The number of the last component and its bit count must be given. The bit counts of all components but the last are set to the first component's max_length*36. All components with numbers greater than the given component are deleted. All components that have been initiated are terminated. A 3-bit switch is used to control these actions. Syntax: declare msf_manager_$adjust entry (ptr, fixed bin, fixed bin(24), bit(3), fixed bin(35)); call msf_manager_$adjust (fcb_ptr, component, bc, switch, code); Arguments: fcb_ptr is a pointer to the file control block. (Input) component is the number of the last component. (Input) bc is the bit count to be placed on the last component. (Input) switch is a 3-bit count/truncate/terminate switch. (Input) bit count "0"b do not set the bit count. "1"b set the bit count. truncate "0"b do not truncate the given component. "1"b truncate the given component to the length specified in the bc argument. terminate "0"b do not terminate the component. "1"b terminate the component. code is a storage system status code. (Output) :Entry: close: 03/19/84 msf_manager_$close Function: This entry point terminates all components that the file control block indicates are initiated and frees the file control block. Syntax: declare msf_manager_$close entry (ptr); call msf_manager_$close (fcb_ptr); Arguments: fcb_ptr is the pointer to the file control block. :Entry: get_ptr: 03/19/84 msf_manager_$get_ptr Function: This entry point returns a pointer to a specified component in the multisegment file. The component can be created if it does not exist. If the file is a single segment file, and a component greater than 0 is requested, the single segment is converted to a component 0. (See also the msf_manager_$msf_get_ptr entry point.) Syntax: declare msf_manager_$get_ptr entry (ptr, fixed bin, bit(1), ptr, fixed bin(24), fixed bin(35)); call msf_manager_$get_ptr (fcb_ptr, component, create_sw, seg_ptr, bc, code); Arguments: fcb_ptr is a pointer to the file control block. (Input) component is the number of the component desired. (Input) create_sw is the create switch. (Input) "1"b create the component if it does not exist. "0"b do not create the component if it does not exist. seg_ptr is a pointer to the specified component in the file, or null (if there is an error). (Output) bc is the bit count of the component. (Output) code is a storage system status code. (Output) It can be: error_table_$noentry if the component requested did not exist and create_sw is off. :Entry: msf_get_ptr: 03/19/84 msf_manager_$msf_get_ptr Function: This entry point returns a pointer to a specified component in the multisegment file. The component can be created if it does not exist. If the file is a single segment file, and the requested component is not component 0, the single segment is converted to a multisegment file. This change does not affect a previously returned pointer to component 0. If the file does not exist, it is created as a "multi-segment file" with a single component. This entry point never creates a single segment file. (See also the msf_manager_$get_ptr entrypoint.) Syntax: declare msf_manager_$msf_get_ptr entry (ptr, fixed bin, bit(1), ptr, fixed bin(24), fixed bin(35)); call msf_manager_$msf_get_ptr (fcb_ptr, component, create_sw, seg_ptr, bc, code); Arguments: fcb_ptr is a pointer to the file control block. (Input) component is the number of the component desired. (Input) create_sw is the create switch. (Input) "1"b create the component if it does not exist. "0"b do not create the component if it does not exist. seg_ptr is a pointer to the specified component in the file, or null (if there is an error). (Output) bc is the bit count of the component. (Output) code is a storage system status code. (Output) It can be: error_table_$noentry if the component requested did not exist and create_sw is off. :Entry: open: 03/19/84 msf_manager_$open Function: The msf_manager_$open entry point creates a file control block and returns a pointer to it. The file need not exist for a file control block to be created for it. Syntax: declare msf_manager_$open entry (char(*), char(*), ptr, fixed bin(35)); call msf_manager_$open (dir_name, entryname, fcb_ptr, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the multisegment file. (Input) fcb_ptr is a pointer to the file control block. (Output) code is a storage system status code. The code error_table_$dirseg is returned when an attempt is made to open a directory. (Output) Notes: If the file does not exist, fcb_ptr is nonnull and the code error_table_$noentry is returned. If the file cannot be opened, fcb_ptr is null and the value of code returned indicates the reason for failure. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved