08/22/83 initiate_file_ The initiate_file_ subroutine contains entry points for making a segment or archive component known with a null reference name. Entry points in initiate_file_: (List is generated by the help command) :Entry: initiate_file_: 03/29/82 initiate_file_ Function: The initiate_file_ entry point, given a directory name, entry name, and access mode, checks that the user's process has at least the desired access on the specified segment. If so, the segment is initiated with a null reference name. This entry point returns a pointer to the base of the segment and the bit count of the segment. Syntax: declare initiate_file_ entry (char (*), char (*), bit (*), pointer, fixed binary (24), fixed binary (35)); call initiate_file_ (dirname, entryname, mode, seg_ptr, bit_count, code); Arguments: dirname is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) mode is the required access mode to the segment. (Input) The first three bits correspond to the modes read, execute, and write. The remaining bits, if any, must be zero. Named constants for the access modes are declared in access_mode_values.incl.pl1. seg_ptr if the segment was made known, this is a pointer to the base of the segment. Otherwise, this is null. (Output) bit_count is the bit count of the segment. (Output) code is a standard status code. (Output) It may have one of the following values: error_table_$no_r_permission read permission was required but not present error_table_$no_e_permission execute permission was required but not present error_table_$no_w_permission write permission was required but not present Notes: The specified segment must exist, and the user must have nonnull access to it, as well as the required modes, in order to make it known. If making the segment known encounters the error_table_$segknown status code, a zero status code is returned instead. This enables the user of this entry point to test either the returned pointer, or the status code, to indicate whether the segment was made known or not. The hcs_$terminate_noname entry point or the terminate_file_ subroutine should be used to make the segment unknown. :Entry: create: 09/22/86 initiate_file_$create Function: initiates the specified segment with a null reference provided that the user's process has at least the desired access to the segment. If the segment does not exist, it will be created . Syntax: dcl initiate_file_$create entry (char (*), char (*), bit (*), pointer, bit (1) aligned, fixed binary (24), fixed binary (35)); call initiate_file_$create (dirname, entryname, mode, seg_ptr, created, bit_count, code); Arguments: dirname is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) mode is the required access mode to the segment. The first three bits correspond to the modes read, execute, and write. The remaining bits, if any, must be zero. Named constants for the access modes are declared in access_mode_values.incl.pl1. (Input) seg_ptr is set to a pointer to the base of the segment if successfull; otherwise, it is set to null. (Output) created is set to "1"b if the segment did not exist and was created by this call; otherwise, it is set to "0"b. (Output) bit_count is set to the bit count of the segment. (Output) code is a standard status code. (Output) It may have one of the following values: error_table_$no_m_permission the segment did not exist and could not be created with the required access. error_table_$no_r_permission read permission was required but not present error_table_$no_e_permission execute permission was required but not present error_table_$no_w_permission write permission was required but not present Notes: If making the segment known encounters the error_table_$segknown status code, a zero status code is returned instead. This enables the user of this entry point to test either the returned pointer, or the status code, to indicate whether the segment was made known or not. The terminate_file_ subroutine should be used to make the segment unknown. If the segment was create by this call and the caller terminates abnormally or its cleanup handler is invoked, the caller may use the delete option of terminate_file_ to remove the segment that was created. :Entry: component: 03/09/82 initiate_file_$component Function: This entry point can make either a segment or an archive component known with a null reference name. If the component name is null, this entry point is identical to initiate_file_. Otherwise, the directory name and entry name arguments are assumed to specify an achive, and the component name specifies a component within that archive. If the user's process has at least the desired acces on the archive segment, and the user desires no more than read access, then the archive is made known with a null reference name, and a segment number is assigned. This entry point returns a pointer to the base of the component and the bit count of the component. Syntax: declare initiate_file_$component entry (char (*), char (*), char (*), bit (*), pointer, fixed binary (24), fixed binary (35)); call initiate_file_$component (dirname, entryname, component_name, mode, component_ptr, bit_count, code); Arguments: dirname is the pathname of the containing directory. (Input) entryname if component_name is null, this is the entryname of the segment. Otherwise, this is the entryname of an archive. The archive suffix must be supplied. (Input) component_name is null, or is the name of a component in the archive. (Input) mode is the required access mode to the segment. (Input) The first three bits correspond to the modes read, execute, and write. The remaining bits, if any, must be zero. Named constants for the access modes are declared in access_mode_values.incl.pl1. component_ptr if the segment was made known, this is a pointer to the base of the segment or the base of the archive component. Otherwise, this is null. (Output) bit_count is the bit count of the segment or archive component. (Output) code is a standard status code. (Output) In addition to the above values, it may have: error_table_$archive_component_modification write permission was required on an archive component Notes: The notes for the initiate_file_ entry point apply to this entry point also. If a nonnull component name is specified, the following constraints apply to the use of this entry point: (1) The component may not be modified. Only read access is permitted. (2) The component is guaranteed to be contiguous and aligned on a word boundary. It is not guaranteed to have any other alignment. (3) No explicit dependence on the format of archives is permitted. This means that only the data starting at the pointer and extending as far as the bit count may be referenced. No data before or after the component may be referenced. ----------------------------------------------------------- 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