04/12/88 mtape_ Notes on the attach description: Syntax: mtape_ vn1 {-comment vn1_str} vn2 {-comment vn2_str} ....... vni {-comment vn_str} {-control_args} Function: The mtape I/O module supports I/O to/from ANSI standard and IBM standard labeled, unlabeled and DOS formatted tape volumes. Arguments: vn1 vn2 ... vni is a list of volume name specifications. Any number of volume names may be specified, but at least one volume name *must* be specified. If any of the requested volume names begins with a "-", then the "-volume" control argument must precede it. -comment vni_str, -com vni_str allows the optional specification of a message to be displayed on the operators console at the time volume vni is to be mounted. The comment text, vni_str, may be from 1 to 64 characters in length and must be quoted if it contains embedded white space. The optional comment specification must follow its corresponding volume specification and precede the next volume specification. Control arguments for attach description: -default_volume_type STR, -dvt STR specifies the volume type (STR) to be used for Per-Format module selection (see "Notes on tape format selection" below) when an unreadable or unlabeled tape is mounted for potential output operations and no "-volume_type" control argument is given. Permissable values for this control argument are "ansi", or "ibm". (Default value is "ansi".) -density N, -den N specifies the recording density for output operations in bits per inch (BPI). For input operations, the density is determined and set automatically by RCP. Permissible values are 200, 556, 800, 1600 and 6250. (Default density is 1600 BPI.) -device N, -dv N specifies the number of tape devices that will be requested to be used simultaneously for multi-volume operations. Permissible values are from 1 to 63. (Default is 1 device.) -display, -ds specifies that the entire attach description, after it has been parsed and any necessary defaults added, will be displayed on the user_output I/O switch. -no_display, -nds specifies that the attach description will not be displayed. (Default) -error, -err specifies that verbose error messages will be displayed when exception conditions (e.g. unrecoverable tape errors) are detected. (Default) -no_error, -nerr specifies that only error codes will be returned upon detection of exception conditions. -label, -lbl specifies that volume and file label records exist and or are to be recorded by the selected Per-Format module. (Default) -no_label, -no_labels, -nlbl specifies that volume and file label records do not exist or are not to be recorded by the selected Per-Format module. If this control argument is given when attempting to select a Per-Format module that does not accept unlabeled tape volumes, the attachment is aborted. -ring, -rg specifies that volumes are to be mounted with write rings installed. -no_ring, -nrg specifies that volumes are to be mounted with no write rings installed. (Default) -speed N1{,N2,...,Nn}, -ips N1{,N2,...,Nn} specifies desired tape drive speed(s) in inches per second (IPS). permissible values are 75, 125 and 200. If more than one speed device is to be used, the optional second and third speed specification must be separated by commas as shown. If this control argument is omitted, RCP will pick any available speed device. -system, -sys specifies that the user is requesting to be considered a system process. -no_system, -nsys specifies that the user is not to be considered a system process. (Default) -track N, -tk N specifies the track type of the tape drive to be used. Permissible values are 7 or 9. (Default is 9 track.) -volume vni, -vol vni specifies that the following volume name (vni) begins with a hyphen ("-") and would otherwise be considered a control argument. -volume_type STR, -vt STR specifies the volume type to be used in Per-Format module selection (See "Notes on tape format selection" below). Permissable values for this control argument are "ansi", or "ibm". (No Default. The volume type is determined by RCP for labeled volumes and by the "-default_volume_type" specification for unlabeled or unreadable volumes.) -wait, -wt specifies that when tape devices are not immediately available from RCP for a requested volume mount, the mtape_ I/O module should wait for the number of minutes specified by the "-wait_time" control argument (or its default value), before reporting an error on the initial volume mount or subsequent volume switching. -no_wait, -nwt specifies that the mtape_ I/O module will not wait for an available device to become free, but instead report an error immediately. (Default) -wait_time N, -wtm N specifies the time (in minutes) that the mtape_ I/O module will wait for unavailable tape drives to become available for volume mounts when the "-wait" control argument is specified. Permissible values range from 1 to 1440 minutes (24 hours). (Default wait time is 10 minutes.) Notes on tape format selection: Unlike other Multics tape I/O modules, mtape_ will process tapes in several different formats (currently limited to ANSI and IBM formats. In order to accommodate this capability, the mtape_ I/O module itself does all of the physical tape I/O and error recovery, but allows all logical file and record level I/O to be performed by a format specific subroutine known as a Per-Format module (PFM). Selection of the appropriate PFM is performed at attach time, after the first volume has been mounted. In the absence of a "-volume_type" specification, the PFM is selected on the basis of the volume_type info returned by RCP. Notes on file opening: Opening a file is accomplished by calling the iox_$open_file entry which accepts as one of its arguments a character string "open description". The open description supplies file attribute and positioning information to the selected PFM. Both the ANSI and IBM PFMs accept sequential_input and sequential_output opening modes. The iox_$open entry is also supported, but merely passes a "null" description to the open_file entry, which in effect applies the default open description values as the total open description. Notes on the open description: syntax: open_spec_1 open_spec_2 ..... open_spec_i where open_spec_1 through open_spec_i are control arguments which define the desired file attributes of the file to be opened. Listed below are those control argument descriptions which are common to both the ANSI and IBM PFMs open descriptions. Control arguments that are specific to each of these PFMs will be listed in separate sections. Control arguments for open description: -append, -app specifies that the requested file is to be appended to the end of the file set as a new file. The requested opening mode must be sequential_output or the file opening will be aborted. -no_append, -napp specifies that the requested file is not to be appended to the end of the file set. (Default) -block N, -bk N specifies the block size in bytes for output operations and is also required for input operations for IBM unlabeled or DOS formatted tapes. For input operations on standard labeled IBM or ANSI tape files, the block size is obtained from the the file header label record. Permissible values are from 18 to 99996 bytes. (Defaults are 2048 bytes for ANSI and 8192 bytes for IBM formats.) -comment STR, -com STR specifies a user comment to be displayed on the user_output I/O switch, after the file has been successfully opened. The comment text (STR) may be from 1 to 80 characters in length. -default_fixed_record N, -dfr N specifies the record length to be used for "f" or "fb" formats in the absence of a "-record" specification. The intended purpose of this control argument is to supply a default value for record size without having to include a "-record" specification in the open description. If the user wishes to explicitly specify the record length, the "-record" control argument should be used. Although the "-default_fixed_record" control argument may appear in a users open description and be processed accordingly, this would not be considered the "proper" method of explicitly supplying the record length. The default value of "N" is set to 80 (for 80 character records) for both the ANSI and IBM PFMs. This default value may be changed by the default setting mechanism (see "Notes on user settable defaults" below). -default_spanned_record N, -dsr N specifies the record length to be used for ANSI "s" or "sb" formats, or IBM "vs" or "vbs" formats, in the absence of a "-record" specification. The intended purpose of this control argument is to supply a default value for record size without having to include a "-record" specification in the open description. If the user wishes to explicitly specify the record length, the "-record" control argument should be used. Although the "-default_spanned_record" control argument may appear in a users open description and be processed accordingly, this would not be considered the "proper" method of explicitly supplying the record length. The default value of "N" is set to 1044480 (sys_info$max_seg_size * 4) for both the ANSI and IBM PFMs. This default value may be changed by the default setting mechanism (see "Notes on user settable defaults" below). -default_variable_record N, -dvr N specifies the record length to be used for ANSI "d" or "db" formats, or IBM "v" or "vb" format in the absence of a "-record" specification. The intended purpose of this control argument is to supply a default value for record size without having to include a "-record" specification in the open description. If the user wishes to explicitly specify the record length, the "-record" control argument should be used. Although the "-default_variable_record" control argument may appear in a users open description and be processed accordingly, this would not be considered the "proper" method of explicitly specifying the record length. The default value of "N" is set equal to the default block size (i.e. 2048 for ANSI and 8192 for IBM). This default value may be changed by the default setting mechanism (see "Notes on user settable defaults" below). -display, -ds specifies that the entire open description, after it has been parsed and any necessary defaults added, is to be displayed on the user_output I/O switch. -no_display, -nds specifies that the open description will not be displayed on the user_output I/O switch. (Default) -expires date, -exp date specifies the expiration date of the file to be created, where date must be of a form acceptable to the convert_date_to_binary_ subroutine. -extend, -ext specifies extension of an existing file. -no_extend, -next specifies that the requested file is not to be extended. (Default) -force, -fc specifies that the expiration date of the file being overwritten is to be ignored. -no_force, -nfc specifies that the expiration date of a file being overwritten is not to be ignored. If the expiration date is not in the past, the user is queried for permission to overwrite the file. (Default) -format F, -fmt F specifies the record format of the file. Permissible values for ANSI: U, F, D, S, FB, DB, and SB; For IBM: U, F, V, VS, FB, VB, and VBS. (They may be specified in either upper or lower case.) (Default values are DB for ANSI format and VB for IBM formats.) -label_entry entry, -lbe entry specifies the entry point of a user subroutine which will be called to process the contents of user label records on input and generate the contents of same, for subsequent writing by mtape_ on output. (See "Notes on calling the user label processing routine" below.) -last_file, -lf specifies that the file to be processed is the last file of the file set. -not_last_file, -nlf specifies that the file to be processed may not be the last file of the file set. (Default) -mode STR, -md STR specifies the encoding mode used to record the file data. Permissible values of STR are ascii, ebcdic or binary. (Default for ANSI format is ascii, for IBM format the default is ebcdic.) -modify, -mod specifies modification of an existing file while retaining the file attributes as recorded in the original files header label records. -no_modify, -nmod specifies that modification of an existing file is not to be performed. (Default) -name STR, -nm STR specifies the file identifier of the requested file. STR can be from 1 to 17 characters. -next_file, -nf specifies the file to be processed as the "next" (or first) file of the file set. This control argument is intended to be used when sequentially processing files. For output operations, if -name and or -number are not specified, the values of their respective fields are fabricated by using the next sequential number as the file sequence number and forming the file name by concatenating the string "FILE" with the alpha-numeric representation of the file number. (i.e. "FILE0001"). (Default) -not_next_file, -nnf specifies that the requested file is not the next file. -number N, -nb N specifies the file sequence number or numerical position within the file set. Permissible values range from 1 to 9999. -record N, -rec N specifies the logical record length in bytes. Permissible values range from 18 to 1044480 (sys_info$max_seg_size * 4) bytes, but the legality of the record size is dependent on the record format specified with the "-format" control argument and the block size. In general the record size must be <= the block size with the exception of "spanned record" formats (i.e. ANSI S or SB formats and IBM VS or VBS formats), where the record size may be the max allowable. (No default value. The default record size is determined by the value of the appropriate "-default_(fixed spanned variable)_record" specification.) -replace STR, -rpl STR specifies replacement of an existing file, where STR is the file identifier to use in the search for the file to be replaced. Notes on the ansi pfms open arguments: Control arguments for ansi pfm open description: -buffer_offset, -bo specifies that each block will be recorded with an 8 character prefix. A template of a block including this prefix has the following format: dcl 1 tape_block aligned based, 2 block_size fixed dec (7, 0) unaligned, 2 block_number fixed dec (7, 0) unaligned, 2 block_data char (tape_block.block_size - 8) unaligned; where: block_size is the block size in 9 bit bytes, including the 8 character prefix. block_number is the numerical sequence number of the block within the current physical file, starting at block number 0. block_data is the user specified data recorded in the block. The length of this field is governed by the user specified block length. The block_size and block_number field are recorded in the packed fixed decimal pl1 data type, so that they may be written in the same manner without regard to interface recording mode (nine bit or binary). The buffer offset prefix length is recorded in the ANSI HDR2 label record buffer offset field (character positions 51 and 52). -no_buffer_offset, -nbo specifies that no block prefix will be recorded in each data block. (Default) -generate, -gen specifies creating a new "generation" of an existing file by replacement. The file attributes recorded in the file header remains the same as the replaced file, but the generation number in the file header is incremented by 1. -no_generate, -ngen specifies that a new generation of an existing file will not be created. (Default) Notes on the ibm pfms open arguments: Control arguments for ibm pfms open description: -dos specifies that the file to be processed is in IBM DOS format. IBM DOS files contain only 1 header label (the HDR1 label) and do not retain any information as to file format, block length and record length. It is therefore necessary to specify the "-block", "-record" and "-format" control arguments (or allow the default values for same to be used) even when opening an IBM DOS file for input. -no_dos, -ndos specifies that the file to be processed is not in IBM DOS format but is in fact in IBM standard OS/VS format. (Default) -system_use specifies that when opening for output, certain fields of the HDR2 and EOV2 label records will be used to record the recording mode (ASCII, EBCDIC or BINARY), and the volume name of the next volume in the volume sequence list. The fields used for these purposes are HDR2 character position 40 for recording mode (recorded as an EBCDIC "1", "2", or "3" for ASCII, EBCDIC, or BINARY respectively), and EOV2 character positions 41 - 46 for the next volume name. The IBM OS/VS Tape Labels specification marks these fields as "reserved for future use". It is therefore recommended that the "-system_use" control argument not be used in an interchange environment. -no_system_use specifies that the HDR2 and EOV2 label record fields mentioned above will not be corrupted. (Default) Notes on file closing: Closing a file is accomplished by calling the iox_$close_file entry which accepts as one of its arguments a character string "close description". The close description supplies close option information to the selected PFM. The iox_$close entry is also supported, but merely passes a "null" description to the close_file entry, which in effect applies the default close description values as the total close description. Notes on the close description: syntax: close_spec_1 close_spec_2 ..... close_spec_i where close_spec_1 through close_spec_i are control arguments which define close time options for the file to be closed. Listed below are those control argument descriptions which are common to both the ANSI and IBM PFMs close descriptions. Control arguments for close description: -close_position STR, -cls_pos STR specifies where to physically position the tape volume within the bounds of the file that is being closed. The values of STR are case insensitive and may be selected from "bof" (for beginning of file), "eof" (for end of file) and "leave" to leave the tape positioned where it is. (Default close position is "leave".) -comment STR, -com STR specifies a user comment to be displayed on the user_output I/O switch, after the file has been successfully closed. The comment text (STR) may be from 1 to 80 characters in length. -display, -ds specifies that the entire close description, after it has been parsed and any necessary defaults added, is to be displayed on the user_output I/O switch. -no_display, -nds specifies that the close description will not be displayed on the user_output I/O switch. (Default) Notes on detaching the i/o switch: Detaching the I/O switch is accomplished by calling the iox_$detach entry which accepts as one of its arguments a character string "detach description". The detach description supplies mtape_ with detach option information. The iox_$detach_iocb entry is also supported, but merely passes a "null" description to the detach entry, which in effect applies the default detach description values as the total detach description. Notes on the detach description: syntax: detach_spec_1 detach_spec_2 ..... detach_spec_i where detach_spec_1 through detach_spec_i are control arguments which define detach time options for mtape_. These control arguments are listed below. Control arguments for detach description: -comment STR, -com STR specifies the contents of an optional comment to be displayed on the operator console when demounting the first volume found that is still mounted. The comment may be from 1 to 65 characters in length. -display, -ds specifies that the entire detach description, after it has been parsed and any necessary defaults added, is to be displayed on the user_output I/O switch. -no_display, -nds specifies that the detach description will not be displayed on the user_output I/O switch. (Default) -rewind, -rew specifies that the remaining mounted volumes are to be rewound to load point upon detachment. (Default) -unload, -unld specifies that the remaining mounted volumes are to be physically unloaded from the tape drive upon detachment. Notes on other supported operations: Besides the attach, open, open_file, close, close_file, detach and detach_iocb operations already described, the mtape_ I/O module supports the following iox_ operations: List of other supported operations: read_record when the I/O switch is open for sequential_input. write_record when the I/O switch is open for sequential_output. position accepts all types of positioning when the I/O switch is open for input except type 3, which is for stream_input only. control see "Notes on supported control operations" below. List of control supported operations: file_status, fst returns a pointer to a structure that contains the status of the current file specified by the open description. File attribute as well as error summary information is included. The format of the structure returned is defined by the "mtape_fst" structure which can be found in the include file "mtape_file_status.incl.pl1". If the pointer is given as null, then mtape_ will allocate the structure for the user. file_set_status, fsst returns a pointer to an array of structures defining the file status for all files in the current file set. The format of the structure returned is defined by the "mtape_fsst" structure which can be found in the include file "mtape_file_status.incl.pl1". If the pointer is given as null, then mtape_ will allocate the structure for the user. force_end_of_volume, feov simulates detection of the end of tape reflective foil upon the next write block operation. The PFM will then close out the volume by writing the EOV trailer labels and request a volume switch for the next volume in the volume sequence list. The I/O switch must be open for sequential_output. hardware_status, hwst returns a pointer to a structure that contains the last hardware status stored. The format of this structure is defined by the include file "mtape_hardware_status.incl.pl1". If the pointer is given as null, then mtape_ will allocate the structure for the user. io_call executes one of the other control operations on behalf of the io_call commands control operation. For any control operation that would normally return a structure to the user, the io_call operation will cause the contents of this structure to be displayed on the I/O switch referenced by the io_call control structures "report" entry variable (normally the user_output I/O switch). ring_in, rin requires that the I/O switch is closed and will cause all currently mounted volumes of the volume set to be demounted. When the next file opening is performed, the required volume will be re-mounted with the write ring installed. volume_status, vst returns a pointer to a structure that contains the status of the current volume. The returned status contains volume attribute as well as volume error summary information. The format of the structure returned is defined by the "mtape_vst" structure which can be found in the include file "mtape_volume_status.incl.pl1". (Note: The include file "mtape_err_stats.incl.pl1" is referenced by the mtape_volume_status include file and must be included.) If the pointer is given as null, then mtape_ will allocate the structure for the user. volume_set_status, vsst returns a pointer to an array of structures defining the volume status for all volumes in the current volume set. The format of the structure returned is defined by the "mtape_vsst" structure which can be found in the include volume "mtape_volume_status.incl.pl1". (Note: The include file "mtape_err_stats.incl.pl1" is referenced by the mtape_volume_status include file and must be included.) If the pointer is given as null, then mtape_ will allocate the structure for the user. Notes on user settable defaults: The default values for the attach, open, close and detach descriptions were picked for their sensibility and the authors experience in how most people process tapes. However, it is recognized that for whatever reason different people and or groups of people may want different default values to suit their needs. Therefore, a command has been written which will allow the attach, open, close and detach description default values to be tailored to a particular groups or persons needs. For further information, type "help mtape_set_defaults". Notes on calling the user label processing routine: In order to process user defined file labels when the "-label_entry" open description argument is used, the entry variable argument to the "-label_entry" control argument must conform to the following calling sequence in order to be called properly by mtape_ and its Per-Format modules: dcl user_label_entry entry (ptr, char (*), fixed bin, fixed bin, fixed bin, fixed bin (35)); call user_label_entry (iocb_ptr, user_label_data, label_number, label_type, file_section_number, code); arguments: iocb_ptr is a pointer to the I/O control block through which the mtape_ I/O module is attached. A user_label_entry routine may wish to know more information about the file for which it is processing user labels. This can be accomplished by calling the iox_$control entry with this iocb_ptr and executing the mtape_ "file_status" control operation. user_label_data is the actual contents of the user label record to be processed (INPUT) or written (OUTPUT). For ANSI and IBM user label records, the length of this field will be 76 characters on input and truncated to same on output. label_number is the number of the user label record within the file label group. The ANSI and IBM standards allow from 1 to 9 user label records within a file label group (UHL1 - UHL9, and UTL1 - UTL9). label_type is the encoded file label group type that the user_label_entry is being called to process label records for. Its possible values are as follows: 1 = Beginning of file (BOF) label group 2 = End of volume (EOV) label group 3 = End of file (EOF) label group file_section_number is the section number of the file for which the user_label_entry routine is being called to process user labels for. For multi-volume files, this would essentially be the number of the volume (the first volume on which a file resides being number 1) on which this file "section" resides. For single volume files, the file_section_number would always be a 1. code is a standard system error code. When writing user labels, the user_label_entry routine should set code to error_table_$end_of_info in order to tell the caller that no more user labels are to be written. Otherwise, the user_label_entry is called repeatedly to generate user label data until the maximum number of user labels have been written. Notes on processing user labels: The user label routine is called by the open, open_file, close, close_file operations and when the end of a tape volume is encountered. The routine must be written to monitor the input argument values (user_label_data, label_number, label_type and code) in order to process each type of label correctly. For output, the user label routine is called repeatedly upon open, close and volume end to support writing of up to nine user labels. The call loop is terminated after the ninth call or when the error_table_$end_of_info error code is returned. For input, the routine is called once for each user label found on the tape. To determine whether the label processing routine is being called to process labels read from a tape or to build new labels for writing, the value of the user_label_data parameter should be checked. If the value is set to spaces, then the label should be constructed by the routine and stored in user_label_data. Otherwise, the information contained in user_label_data should be processed as input. The label_type parameter value is set by the caller. The label processing routine should check this value to determine the type of user label to process. The label_number parameter value is set by the caller. The label processing routine should check this value to determine which label within type should be processed. It is up to the writer of the routine to set the code parameter to error_table_$end_of_info and return it. Setting this value will stop the call loop for the current label building operation. ----------------------------------------------------------- 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