09/22/86 archive_ The archive_ subroutine is used to access individual components in archives, list the components of an archive, and obtain information about archive components. Entry points in archive_: (List is generated by the help command) :Entry: get_component: 03/18/81 archive_$get_component Function: This entry, given a pointer to an archive and its bitcount, and the name of the desired component in the archive, returns a pointer to the component and the bitcount of the component. Syntax: dcl archive_$get_component entry (pointer, fixed bin (24), char (*), pointer, fixed bin (24), fixed bin (35)); call archive_$get_component (archive_ptr, archive_bc, component_name, component_ptr, component_bc, code); Arguments: archive_ptr is a pointer to the base of the archive segment to be searched. It need not point to the base of a segment; it is converted to a segment base pointer by archive_, so a pointer to anywhere in the segment may be given here. (Input) archive_bc is the bitcount of the archive segment. (Input) component_name is the name of the component to be searched for. It may be up to 32 characters long. (Input) component_ptr is a pointer to the first word of the archive component if the specified component was found, or null otherwise. It is a pointer into the segment pointed to by archive_ptr. (Output) component_bc is the bitcount of the archive component pointed to by component_ptr. It describes a region of the archive segment which contains the specified component; if an attempt is made to reference past the end of this area, invalid data may be referenced. (Output) code is a standard system status code, one of the following: (Output) error_table_$no_component error_table_$not_archive error_table_$archive_fmt_err :Entry: get_component_info: 03/18/81 archive_$get_component_info Function: This entry, given a pointer to an archive and its bitcount, and the name of the desired component in the archive, fills in a caller-supplied structure with information describing the archive component. Also see archive_$get_component and archive_$next_component_info. Syntax: dcl archive_$get_component_info entry (pointer, fixed bin (24), char (*), pointer, fixed bin (35)); call archive_$get_component_info (archive_ptr, archive_bc, component_name, archive_component_info_ptr, code); Arguments: archive_ptr is a pointer to the base of the archive segment to be searched. It need not point to the base of a segment; it is converted to a segment base pointer by archive_, so a pointer to anywhere in the segment may be given here. (Input) archive_bc is the bitcount of the archive segment. (Input) component_name is the name of the component to be searched for. It may be up to 32 characters long. (Input) archive_component_info_ptr is a pointer to a user-supplied archive_component_info structure, described below. The caller must have previously set archive_component_info.version to the appropriate version number, currently ARCHIVE_COMPONENT_INFO_VERSION_1. The structure is filled in with information describing the selected archive component if it can be found. (Input) code is a standard system status code. (Output) It may be one of the following: error_table_$no_component error_table_$not_archive error_table_$archive_fmt_err error_table_$unimplemented_version Structure: The archive_component_info_ptr points to the following structure (described in the archive_component_info.incl.pl1 include file): dcl 1 archive_component_info aligned based (archive_component_info_ptr), 2 version fixed bin, 2 comp_bc fixed bin (24), 2 comp_ptr ptr, 2 name char (32) unaligned, 2 time_modified fixed bin (71), 2 time_updated fixed bin (71), 2 comp_lth fixed bin (19), 2 access bit (36) unaligned; List of structure elements: version must be set to ARCHIVE_COMPONENT_INFO_VERSION_1 by the caller. All other structure elements are output. comp_bc is the bit_count of the archive component. comp_ptr is a pointer to the base of the component. name is the name of the component. time_modified is a clock reading corresponding to the date/time contents modified of the segment from which this component was most recently updated. This is the value reported in the "modified" column by the "ac tl" command. It may be inaccurate by several hours if the archive was updated in a different time zone from the current time zone. time_updated is a clock reading corresponding to the date/time when this component was last updated in the archive. This is the value reported in the "updated" column by the "ac tl" command. It may be inaccurate by several hours if the archive was updated in a different time zone from the current time zone. comp_lth is the size, in words, of the component. Both the size in words and the bit_count are provided as a convenience to the caller. The size in words is derived from the bit_count. access is the representation of the effective access mode recorded with the archive component. The first bit is "r" access, the second is "e", and the third is "w". Even if "a" access appears in the archive itself, it will be ignored. :Entry: next_component: 03/18/81 archive_$next_component Function: This entry, given a pointer to an archive and its bitcount, and a pointer to the base of a component (or null), returns a pointer to the next component in the archive, its name, and its bitcount. If there are no components remaining in the archive, the pointer is returned null on output. The first time this is called for a particular archive, the component pointer should be supplied as null. Syntax: dcl archive_$next_component entry (pointer, fixed bin (24), pointer, fixed bin (24), char (*), fixed bin (35)); call archive_$next_component (archive_ptr, archive_bc, component_ptr, component_bc, component_name, code); Arguments: archive_ptr is a pointer to the base of the archive segment to be searched. It need not point to the base of a segment; it is converted to a segment base pointer by archive_, so a pointer to anywhere in the segment may be given here. (Input) archive_bc is the bitcount of the archive segment. (Input) component_ptr on input, this is a pointer to the previous component in the archive, or null to indicate that the next component should be the first component in the archive. On output, this is a pointer to the next component in the archive, or null if there are no components remaining after the one it pointed to on input. (Input/Output) component_bc is the bitcount of the selected component. (Output) component_name is the name of the selected component. (Output) code is a standard system status code, one of the following; (Output) error_table_$not_archive error_table_$archive_fmt_err :Entry: next_component_info: 03/18/81 archive_$next_component_info Function: This entry, given a pointer to an archive, the bitcount of the archive, and a pointer to the base of a component (or null), returns a pointer to the next component in the archive and fills in a archive_component_info structure to describe it. If there are no components remaining in the archive, the pointer is returned null on output. The first time this is called for a particular archive, the component pointer should be supplied as null. See also archive_$get_component_info and archive_$next_component. Syntax: dcl archive_$next_component_info entry (pointer, fixed bin (24), pointer, pointer, fixed bin (35)); call archive_$next_component_info (archive_ptr, archive_bc, component_ptr, archive_component_info_ptr, code); Arguments: archive_ptr is a pointer to the base of the archive segment to be searched. It need not point to the base of a segment; it is converted to a segment base pointer by archive_, so a pointer to anywhere in the segment may be given here. (Input) archive_bc is the bitcount of the archive segment. (Input) component_name is the name of the component to be searched for. It may be up to 32 characters long. (Input) archive_component_info_ptr is a pointer to a user-supplied archive_component_info structure, described in the description of the archive_$get_component_info entrypoint. The caller must have previously set archive_component_info.version to the appropriate version number, currently ARCHIVE_COMPONENT_INFO_VERSION_1. The structure is filled in with information describing the selected archive component if component_ptr is returned non-null. (Input) code is a standard system status code. (Output) It may be one of the following: error_table_$not_archive error_table_$archive_fmt_err error_table_$unimplemented_version :Entry: list_components: 03/18/81 archive_$list_components Function: This entry, given a pointer to an archive and its bitcount, and a pointer to an area, allocates an array of archive_component_info structures in the area to describe all the components in the archive, and returns a pointer to and the size of this array. Syntax: dcl archive_$list_components entry (pointer, fixed bin (24), fixed bin, pointer, pointer, fixed bin, fixed bin (35)); call archive_$list_components (archive_ptr, archive_bc, info_version, area_ptr, archive_component_info_array_ptr, n_components, code); Arguments: archive_ptr is a pointer to the base of the archive segment to be searched. It need not point to the base of a segment; it is converted to a segment base pointer by archive_, so a pointer to anywhere in the segment may be given here. (Input) archive_bc is the bitcount of the archive segment. (Input) info_version is the version number for the archive_component_info structure array which will be allocated and returned. The only supported version is ARCHIVE_COMPONENT_INFO_VERSION_1. (Input) area_ptr is a pointer to a caller-supplied area in which the returned array of archive_component_infos will be allocated. If area_ptr is null, no list will be allocated, but n_components will still be set; this can be used when it is desired to merely count the components in the archive. (Input) archive_component_info_array_ptr is a pointer returned which points to an array of archive_component_info structures describing all the components in the archive. It should be declared as follows: (Output) dcl 1 archive_component_info_array (n_components) aligned like archive_component_info based (archive_component_info_array_ptr); n_components is the number of components in the archive. This may be zero if the archive is empty, and is still valid. (Output) code is a standard system status code, one of the following; (Output) error_table_$not_archive error_table_$archive_fmt_err ----------------------------------------------------------- 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