08/22/83 tape_ibm_ Function: The tape_ibm_ I/O module implements the processing of magnetic tape files in accordance with the standards established by the following IBM publications: "OS Data Management Services Guide", Release 21.7, GC26-3746-2; "IBM System 360 Disk Operating System Data Management Concepts", GC24-3427-8; and "OS Tape Labels", Release 21, GC28-6680-4. These documents are collectively referred to below as the Standard. Entries in the module are not called directly by users; rather, the module is accessed through the I/O system. See the Programmer's Reference Manual for a general description of the I/O system. Definition of Terms: record related information treated as a unit of information. block a collection of characters written or read as a unit. A block may contain one or more complete records, or it may contain parts of one or more records. A part of a record is a record segment. A block does not contain multiple segments of the same record. file a collection of information consisting of records pertaining to a single subject. A file may be recorded on all or part of a volume, or on more than one volume. volume a reel of magnetic tape. A volume may contain one or more complete files, or it may contain sections of one or more files. A volume does not contain multiple sections of the same file. file set a collection of one or more related files, recorded consecutively on a volume set. volume set a collection of one or more volumes on which one and only one file set is recorded. Syntax of Attach Description: tape_ibm_ vn1 vn2 ... vnN {-control_args} Arguments: vni is a volume specification. A maximum of 64 volumes may be specified. In the simplest (and typical) case, a volume specification is a volume name that must be six characters or less in length. If a volume name is less than six characters and entirely numeric, it is padded on the left with 0's. If a volume name is less than six characters and not entirely numeric, it is padded on the right with blanks. Occasionally, keywords must be used with the volume name. For a discussion of volume name and keywords see "Volume Specification" below. vn1 vn2 ... vnN comprise what is known as the volume sequence list. The volume sequence list may be divided into two parts. The first part, vn1 ... vni, consists of those volumes that are actually members of the volume set, listed in the order that they became members. The entire volume set membership need not be specified in the attach description; however, the first (or only) volume set member MUST be specified, because its volume name is used to identify the file set. If the entire membership is specified, the sequence list may contain a second part, (vni+1) ... vnN, consisting of potential members of the volume set, listed in the order that they may become members. These volumes are known as volume set candidates. (See "Volume Switching" below.) Control arguments: A control argument can appear only once. -block B, -bk B specifies the block length in characters, where 20<=B<32760 and mod(B,4)=0 if open for sequential output. The value of B is dependent upon the value of R specified in the -record control argument. (See "Creating A File" below.) -clear, -cl specifies that internal information on a file-set which the I/O module retains from previous attachments is to be deleted. This control argument can be used when it is desired to change attributes of a file-set which are maintained across attachments for a given process, e.g. density or label standard. For the initial attachment to a file-set in a given process, this control argument has no effect. -comment STR specifies that a given message is to be displayed on the operator's console whenever a certain volume is mounted. (See Volume Specification" below.) STR can be 64 characters or less in length. -create, -cr specifies that a new file is to be created. (See "Creating A File" below.) -density N, -den N specifies the density at which the file set is recorded, where N can be 800, 1600, or 6250 bits per inch. (See "File Set Density" below.) -device N, -dv N specifies the maximum number of tape drives that can be used during an attachment, where N is an integer in the range 1 <= N <= 63. (See "Multiple Devices" below.) -dos specifies that a file was produced by, or is destined for, a DOS installation. (See "DOS Files" below.) -expires date, -exp date specifies the expiration date of the file to be created or generated where date must be of a form acceptable to the convert_date_to_binary_ subroutine. (See "File Expiration" below.) -extend, -ext specifies extension of an existing file. (See "Extending a File" below.) -force, -fc specifies that the expiration date of the file being overwritten is to be ignored. (See "File Expiration" below.) -format F, -fmt F specifies the record format, where F is a format code: fb, f, vb, v, vbs, vs, or U. (See "Creating A File" below for a description of format codes.) -mode STR, -md STR specifies the encoding mode used to record the file data, where STR is the string ebcdic, ascii, or binary; the default is ebcdic. (See "Encoding Mode" below.) -modify, -mod specifies modification of an existing file. (See "Modifying a File" below.) -name STR, -nm STR specifies the file identifier of the file, where STR is from 1 to 17 characters. (See "File Identifiers" below.) -no_labels, -nlb specifies that unlabeled tapes are to be processed. (See "Unlabeled Tapes" below.) -number N, -nb N specifies the file sequence number, the position of the file within the file set, where N is an integer in the range 1 <= N <= 9999. (See "Creating A File" below.) -record R, -rec R specifies the record length in characters, where R must be in the range 1<=R<1044480. The value of R is dependent upon the choice of record format. (See "Creating A File" below.) -replace STR, -rpl STR specifies the file identifier of the file to be replaced, where STR must be from 1 to 17 characters. If no file with file identifier STR exists, an error is indicated. (See "Creating A File" below.) -retain STR, -ret STR specifies retention of resources across attachments, where STR specifies the detach-time resource disposition: All or none. (See "Resource Disposition" below.) -ring, -rg specifies that the volume set be mounted with write rings. (See "Write Rings and Write Protection" below.) -speed S1{,S2,...,SN}, -ips S1{,S2,...,SN} specifies desired tape drive speeds in inches per second, where Si can be 75, 125, or 200 inches per second. (See "Device Speed Specification" below.) -volume vni specifies a volume name beginning with a hyphen (-) to distinguish it from a control argument. File Identifiers: Associated with every file is a name (file identifier) and a number (file sequence number). The file identifier must be 17 characters or less. When creating a file, the file identifier must be composed of one or more components of one to eight characters, with adjacent components separated by a period. The first character of each component must be an uppercase letter or national character (@, #, or $) and the remaining characters must be uppercase letters, national characters or the digits 0 to 9. If a file identifier (of an existing file) does not meet the naming conventions established for files created on the Multics system, the file must be referenced using the -number control argument and a file sequence number. Creating a File: When a file is created, an entirely new entity is added to the file set. There are two modes of creation: append and replace. In append mode, the new file is added to the file set immediately following the last (or only) file in the set. The process of appending does not alter the previous contents of the file set. In replace mode, the new file is added by replacing (overwriting) a particular previously existing file. The replacement process logically truncates the file set at the point of replacement, destroying all files (if any) that follow consecutively from that point. The -create and -name STR control arguments are required to create a file, where STR is the file identifier. If no file having file identifier STR exists in the file set, the new file is appended to the file set; otherwise, the new file replaces the old file of the same name. If the user wishes to explicitly specify creation by replacement, the particular file to be replaced must be identified. Either a file identifier or a file sequence number is sufficient to uniquely identify a particular file in the file set. The -number and -replace control arguments either separately or in conjunction, are used to specify the file to be replaced. If used together, they must both identify the same file; otherwise, an error is indicated. When the -number control argument is specified, if N is less than or equal to the sequence number of the last file in the file set, the created file replaces the file having sequence number N. If N is one greater than the sequence number of the last file in the file set, the created file is appended to the file set. If N is any other value, an error is indicated. When creating the first file of an entirely new file set, the -number control argument must be explicitly specified. (See "Volume Initialization" below.) The -format, -record and -block control arguments are used to specify the internal structure of the file to be created. They are collectively known as structure attribute control arguments. When the -format control argument is used, F must be one of the following format codes, chosen according to the nature of the data to be recorded. (For a detailed description of the various record formats, see "Record Formats" below.) fb for fixed-length records. Used when every record has the same length, not in excess of 32760 characters. vb for variable-length records. Used when records are of varying lengths, the longest not in excess of 32752 characters. vbs for spanned records. Used when the record length is fixed and in excess of 32760 characters, or variable and in excess of 32752 characters. In either case, the record length cannot exceed 1,044,480 characters. (See "DOS Files" below.) f for fixed-length records, unblocked. v for variable-length records, unblocked. vs for spanned records, unblocked. (See "DOS Files" below.) NOTE: Because of padding requirements records recorded using vs format may be irreversibly modified. (See "Padding" below.) Unblocked means that each block contains only one record (f, v) or record segment (vs). Because of their relative inefficiency, the use of unblocked formats in general is discouraged. Blocked means that each block contains as many records (fb, vb) or record segments (vbs) as possible. The actual number of records/block is either fixed (fb), depending upon the block length and record length, or variable (vb, vbs), depending upon the block length, record length, and actual records. u for undefined records. U format records are undefined in format. Each block is treated as a single record, and a block may contain a maximum of 32760 characters. When the -record control argument is used, the value of R is dependent upon the choice of record format. In the following list, amrl is the actual or maximum record length. F = fb | f: R = amrl F = vb | v: amrl + 4 <= R <= 32756 F = vbs | vs: amrl <= R <= 1044480 F = u: R is undefined (the -record control argument should not be used.) When the -block control argument is used, the value of B is dependent upon the value of R. When the block length is not constrained to a particular value, the largest possible block length should be used. F = fb: B must satisfy mod (B,R) = 0 F = f: B = R F = vb: b >= R + 4 F = v: B = R + 4 F = vbs | vs: 20 <= B <= 32760 F = u: amrl <= B <= 32760 In every case, B must be an integer in the range 20 <= B <= 32760, and, when the I/O switch is opened for sequential_output, must satisfy mod (B,4) = 0. Since the structure attribute control arguments are interdependent, care must be taken to ensure that specified values are consistent. Padding: Since the Multics system is implemented on word-oriented hardware, records recorded in any format are subject to block and/or record padding. On output, the hardware requires that the number of characters in a block be evenly divisible by 4; i.e., only words can be written. The I/O module therefore requires that mod (B,4) = 0, and pads a record, if necessary, to meet this requirement. (Warning: this padding may cause IBM-system rejection of a block if block length is not a multiple of the record length.) The following rules govern padding on output: F = fb: if iobl (the I/O buffer length in an iox_$write_record call; i.e., the number of characters to be written) is less than R, the record is padded on the right with blanks to length R. The last (or only) record of the file may be padded on the right with N blanks, where 0 <= N <= 19 is sufficient to satisfy B >= 20, and mod (B,4) = 0. F = f: if iobl is less than R, the record is padded on the right with blanks to length R. Because the specified value of B must satisfy B >= 20, mod (B,4) = 0, and R = B, there are no other padding possibilities. F = vb: the last (or only) record in every block is padded on the right with N blanks, where 0 <= N <= 12 is sufficient to satisfy B >= 20, and mod (B,4) = 0. Because the number of records in a block is variable, it is difficult to determine which records of a file are padded, if any. F = v: every record is padded on the right with N blanks, where 0 <= N <= 12 is sufficient to satisfy B >= 20, and mod (B,4) = 0. F = vbs: the last (or only) record of the file is padded on the right with N blanks, where 0 <= N <= 12 is sufficient to satisfy B >= 20, and mod (B,4) = 0. F = vs: every record or record segment is padded on the right with N blanks, where 0 <= N <= 12 is sufficient to satisfy B >= 20, and mod (B,4) = 0. NOTE: This requirement can result in an indeterminate number of blanks being inserted into a record at one or more indeterminate positions. F = u: every record is padded on the right with N blanks, where 0 <= N <= 12 is sufficient to satisfy B >= 20, and mod (B,4) = 0. Reading A File: The attach description needed to read a file is less complex than the description used to create it. When a file is initially created by the I/O module, the structure attributes specified in the attach description are recorded in the file's header and trailer labels. These labels, that precede and follow each file section, also contain the file name, sequence number, block count, etc. Files created by OS installations also record the structure attributes in the file labels. (See "DOS Files" below.) When a file is subsequently read, all this information is extracted from the labels. Therefore, the attach description need only identify the file to be read; no other control arguments are necessary. The file can be identified using the -name control argument, the -number control argument, or both in combination. If the -name control argument is used, a file with the specified file identifier must exist in the file set; otherwise, an error is indicated. If the -number control argument is used, a file with the specified file sequence number must exist in the file set; otherwise, an error is indicated. If the -name and -number control arguments are used together, they must both refer to the same file; otherwise, an error is indicated. DOS Files: Files created by DOS installations differ from OS files in one major respect -- DOS does not record HDR2 labels, which contain the structure attributes. It is therefore necessary to specify all of the structure attributes whenever a file created by a DOS installation is to be processed. It is further necessary to distinguish between OS and DOS files recorded in VBS or VS format. The segment descriptor word (SDW) of a zero-length DOS spanned record has a high-order null record segment bit set, while a zero-length OS spanned record does not. (See "V(B)S Format" below, for an explanation of the SDW.) The -dos control argument must be used when writing a VBS or VS file destined for a DOS installation, or when reading a VBS or VS file written by a DOS installation. In the interest of clarity, however, it is recommended that the control argument always be specified when DOS files are processed, regardless of record format. Output Operations On Existing Files: There are two output operations that can be performed on an already existing file: extension and modification. As their functions are significantly different, they are described separately below. They do, however, share a common characteristic. Like the replace mode of creation, an output operation on an existing file logically truncates the file set at the point of operation, destroying all files (if any) that follow consecutively from that point. Because the block length is constrained to mod(B,4) = 0 for output operations, a file whose block length does not satisfy this criterion cannot be extended or modified. Extending A File: It is often necessary to add records to a file without in any way altering the previous contents of the file. This process is known as extension. Because all the information regarding structure, length, etc., can be obtained from the file labels, the attach description need only specify that an extend operation is to be performed on a particular file. (See "DOS Files" above.) If the file to be extended does not exist, an error is indicated. New data records are appended at the end of the file; the previous contents of the file remain unchanged. The file to be extended is identified using the -name control argument, the -number control argument, or both in combination. The same rules apply as for reading a file. (See "Reading a File" above.) The user may specify any or all of the structure attribute control arguments when extending a file. The specified control arguments are compared with their recorded counterparts; if a discrepancy is found, an error is indicated. Modifying A File: It is occasionally necessary to replace the entire contents of a file, while retaining the structure of the file itself. This process is known as modification. Because all necessary information can be obtained from the file labels, the attach description need only specify that a modify operation is to be performed on a particular file. (See "DOS Files" above.) If a file to be modified does not exist, an error is indicated. The entire contents of the file are replaced by the new data records. The file to be modified is identified using the -name control argument, the -number control argument, or both in combination. The same rules apply as for reading a file. (See "Reading a File" above.) If any or all of the structure attribute control arguments are specified, they must match their recorded counterparts; otherwise, an error is indicated. Encoding Mode: The I/O module makes provision for three data encoding modes: EBCDIC, binary, and ASCII. The default data encoding mode is EBCDIC. File labels are always recorded using the EBCDIC character set. When a file is created, the -mode control argument can be used to explicitly specify the encoding mode (if not used, the list_tape_contents command does not supply the specific mode in its report). If STR is the string ascii, the octal values of the characters to be recorded must be in the range 000 <= octal_value <= 377; otherwise, an unrecoverable I/O error occurs. If STR is the string ebcdic, the octal values of the characters to be recorded must be in the range 000 <= octal_value <= 177. (See the ascii_to_ebcdic_ subroutine for the specific ASCII to EBCDIC mapping used by the I/O module.) If STR is the string binary, any 9-bit byte value can be recorded. However, data written on IBM equipment with binary mode may not be compatible with Multics, or vice versa. Because the data encoding mode is not recorded in the file labels, the -mode ascii and the -mode binary control arguments must always be specified when subsequently processing an ASCII or binary file, respectively. File Expiration: Associated with every file is a file expiration date, recorded in the file labels. If a file consists of more than one file section, the same date is recorded in the labels of every section. A file is regarded as "expired" on a day whose date is later than or equal to the expiration date. Only when this condition is satisfied can the file (and by implication, the remainder of the file set) be overwritten. Extension, modification, and the replace mode of creation are all considered to be overwrite operations. The expiration date is recorded in Julian form; i.e., yyddd, where yy are the last two digits of the year, and ddd is the day of the year expressed as an integer in the range 1 <= ddd <= 366. A special case of the Julian date form is the value "00000", which means always expired. The expiration date is set only when a file is created. Unless a specific date is provided, the default value "00000" is used. The -expires control argument is used to specify an expiration date where date must be of a form acceptable to the convert_date_to_binary_ subroutine; the date may be quoted and contain embedded spaces; Julian form, including "00000", is unacceptable. Because overwriting a file logically truncates the file set at the point of overwriting, the expiration date of a file must be earlier than or equal to the expiration date of the previous file (if any); otherwise, an error is indicated. If an attempt is made to overwrite an unexpired file, the user is queried for explicit permission. (See "Queries" below). The -force control argument unconditionally grants permission to overwrite a file without querying the user, regardless of "unexpired" status. Volume Specification: The volume name (also called the slot identifier) is an identifier physically written on, or affixed to, the reel or container of the volume. The volume identifier is a six-character identifier magnetically recorded in the first block of the volume, the VOL1 label. This implementation of the I/O module assumes the volume name and volume identifier to be identical. If this is not the case, the volume identifier must be used in the volume specification field of the attach description. If a volume name begins with a hyphen (-), the -volume keyword must precede the volume name. Even if the volume name does not begin with a hyphen, it may still be preceded by the -volume keyword. The volume specification has the following form: -volume vni Occasionally, it is necessary for a user to communicate some additional information to the operator in connection with a mount request. This can be done through the use of the -comment control argument: vni -comment STR or: -volume vni -comment STR where the -comment STR keyword and text specify that a given message is to be displayed on the operator's console whenever volume vni is mounted (a comment can be specified after each volume name supplied). STR can be from 1 to 64 characters. STR must be quoted if it contains embedded spaces. Volume Switching: The Standard defines four types of file set configurations: single-volume file a single file residing on a single volume. multivolume file a single file residing on multiple volumes. multifile volume multiple files residing on a single volume. multifile multivolume multiple files residing on multiple volumes. The I/O module maintains a volume sequence list on a per-file-set basis, for the life of a process. A minimal volume sequence list contains only one volume, the first (or only) volume set member. If the file set is a multivolume configuration, the sequence list may contain one or more of the additional volume set members, following the mandatory first volume. If the sequence list contains the entire volume set membership (which may be only one volume), it may then contain one or more volume set candidates. Volume set candidates can become volume set members only as the result of an output operation. When an output operation causes the amount of data in the file set to exceed the capacity of the current volume set membership, the first available volume set candidate becomes a volume set member. When the first attachment to any file in a file set is made, the volume sequence list for the file set is initialized from the attach description. At detach time, the I/O module empirically determines that one or more volumes are volume set members, by virtue of having used them in the course of processing the attached file. The remaining volumes in the sequence list, if any, are considered to be candidates. In subsequent attachments to any file in the file set, the order of volumes specified in the attach description is compared with the sequence list. For those volumes that the I/O module knows to be volume set members, the orders must match; otherwise, an error is indicated. Those volumes in the sequence list that the I/O module considers to be candidates are replaced by attach description specifications, if the orders differ. If the attach description contains more volumes than the sequence list, the additional volumes are appended to the list. This implementation maintains and validates the volume set membership on a per-process basis, and maintains a list of volume set candidates that is alterable on a per-attach basis. Once a volume sequence list exists, subsequent attachments to files in the file set do not require repeated specification of any but the first (or only) volume, which is used to identify the file set. If the I/O module detects physical end of tape in the course of an output operation, it prepares to switch to the next volume in the volume set. An attempt is made to obtain the volume name from the sequence list, either from the sublist of members, or the sublist of candidates. If the list of volume set members is exhausted, and the list of candidates is either empty or exhausted, the user is queried for permission to terminate processing. If the reply is negative, the I/O module queries for the volume name of the next volume, which becomes a volume set member and is appended to the volume sequence list. If a volume name is obtained by either method, volume switching occurs, and processing of the file continues. If the I/O module reaches end-of-file section (but not of file) in the course of an input operation, it first attempts to obtain the next volume name from the volume sequence list. No distinction is made between the member and candidate sublists, because a volume that ends with a file section must be followed by the volume that contains the next section. If the sequence list is exhausted, the user is queried as described above. If either of these methods results in a volume name, volume switching occurs and processing of the file continues. If the volume set is demounted at detach time, all volume set candidates are purged from the volume sequence list. Multiple Devices: If a volume set consists of more than one volume, the -device control argument can be used to control device assignment, where N specifies the maximum number of tape drives that can be used during this attachment (N is an integer in the range 1 <= N <= 63). Drives are assigned only on a demand basis, and in no case does the number actually assigned exceed the device limit of the process. The default for an initial attachment to a file in a file set is N equals 1; the default for a subsequent attachment to that file or any other in the file set equals the previous value of N. File Set Density: The I/O module makes provision for three densities: 800, 1600, and 6250 bpi (bits per inch). Every file in a file set must be recorded at the same density; otherwise, an error is indicated. The -density control argument is used to explicitly specify the file set density, where N specifies the density at which the file set is (to be) recorded (N can be 800, 1600, and 6250 bpi). The file set density can only be changed in a subsequent attachment if the volume set was demounted by the previous attach. In the absence of a -density control argument, the file set density is determined as follows: open for input: N = density of VOL1 label open for output, creating new file set: N = 1600 bpi open for output, old file set: N = density of VOL1 label Device Speed Specification: The -speed control argument is used to specify acceptable tape device speeds in inches per second. The module only attaches a device that matches a speed specified by this control argument. If more than one speed is specified, the module attaches a device that matches one of the speeds. If more than one device is attached, and more than one speed is specified, the devices will not necessarily all be of the same speed. Opening: The opening modes supported are sequential_input and sequential_output. An I/O switch can be opened and closed any number of times in the course of a single attachment. Such a series of openings may be in either or both modes, in any valid order. All openings during a single attachment are governed by the same attach description. The following control arguments, all of which pertain to output operations, are ignored when the switch is opened for sequential_input: -create -force -expires -modify -extend -replace Resource Disposition: The I/O module utilizes two types of resources: devices (tape drives), and volumes. Once an I/O switch is attached, resources are assigned to the user's process on a demand basis. When the I/O switch is detached, the default resource disposition unassigns all devices and volumes. If several attaches and detaches to a file set are made in a process, repeated assignment and unassignment of resources is undesirable. Although the processing time required to assign and unassign a device is small, all available devices can be assigned to other processes in the interval between one detach and the next attach. While volumes are not often "competed" for, mounting and demounting is both time-consuming and expensive. The -retain control argument is used to specify retention of resources across attachments, where STR specifies the detach-time resource disposition. If STR is the string all, all devices and volumes remain assigned to the process. If STR is the string none, all devices and volumes are unassigned. This is the default retention. The I/O module provides a further means for specifying or changing the resource disposition subsequent to attachment. If retention of any devices or volumes has been specified at or subsequent to attach time using the retention control operation, the unassign_resource command cannot be used. Instead, use the retain_none or retention -none control operation before detaching the I/O module. (See the retention, retain_none, retain_all operations under "Control Operations" below.) Write Rings And Write Protection: Before a volume can be written on, a write ring (an actual plastic ring) must be manually inserted into the reel. This can only be done before the volume is mounted on a device. When a volume is needed, the I/O module sends the operator a mount message that specifies if the volume is to be mounted with or without a ring. If the attach description contains any of the output control arguments (-extend, -modify, or -create), volumes are mounted with rings; otherwise, they are mounted without rings. When a volume set mounted with rings is opened for sequential_input, hardware file protect is used to inhibit any spurious write operations. A volume set mounted without rings cannot be opened for sequential_output. However, the following sequence of events is possible. An attach description contains none of the output control arguments, but does contain the "-retain all" control argument. The volume set is mounted without rings. After one or more (or no) openings for sequential_input, the I/O switch is detached. The volume set remains mounted because of the "-retain all" control argument. Subsequently, an attach is made whose description contains an output control argument, which requires that the volume set be mounted with rings. However, as rings can only be inserted in a demounted volume, the entire volume set must be demounted and then remounted. This situation can be avoided by using the -ring (-rg) control argument to specify that the volume set be mounted with write rings. If no output control argument is specified in conjunction with -ring, the I/O switch cannot be opened for sequential_output. When a volume set is mounted with write rings and the I/O switch is opened for sequential_input, the hardware file protect feature is used to safeguard the file set. Queries: Under certain exceptional circumstances, the I/O module queries the user for information needed for processing to continue or instructions on how to proceed. Querying is performed by the command_query_ subroutine. The user may intercept one or more types of query by establishing a handler for the command_question condition, which is signalled by the command_query_ subroutine. Alternately, the answer command can be used to intercept all queries. The use of a predetermined "yes" answer to any query causes those actions to be performed that attempt to complete an I/O operation without human intervention. In the following list of queries, status_code refers to command_question_info.status_code. See the Programmer's Reference Manual for information regarding the command_question condition and the command_question_info structure. status_code = error_table_$file_aborted This can occur only when the I/O switch is open for sequential_output. The I/O module is unable to correctly write file header labels, trailer labels, or tapemarks. This type of error invalidates the structure of the entire file set. Valid file set structure can only be restored by deleting the defective file or file section from the file set. The user is queried for permission to delete the defective file or file section. If the response is "yes", the I/O module attempts deletion. The attempt may or may not succeed; the user is informed if the attempt fails. If the response is "no", no action is taken. The user is probably unable to subsequently process the file, or append files to the file set; however, this choice permits retrieval of the defective file with another I/O module. In either case, the I/O switch is closed. status_code = error_table_$unexpired_volume This can occur only when the I/O switch is open for sequential_output. A volume must be either reinitialized or overwritten; however, the first file or file section on the volume is unexpired. The user is queried for permission to initialize or overwrite the unexpired volume. If the response is "yes", the volume is initialized or overwritten and processing continues. If the response is "no", further processing cannot continue, and the I/O switch is closed. status_code = error_table_$uninitialized_volume A volume requires reinitialization or user verification before it can be used to perform any I/O. The I/O module distinguishes among four causes by setting command_question_info.query_code as follows: query_code = 1 the first block of the tape is unreadable. The tape is either defective, or recorded at an invalid density. This query code can occur only if the I/O stream is opened for sequential_output. query_code = 2 the first block of the tape is not a valid IBM VOL1 label. The tape is not formatted as an IBM SL volume. This query code can occur only if the I/O stream is opened for sequential_output. query_code = 3 the volume identifier recorded in the VOL1 label is incorrect. The volume identifier does not match the volume name. query_code = 4 the density at which the volume is recorded is incorrect. The volume density does not match the specified density. This query code can occur only if the I/O stream is opened for sequential_output. If the response is "yes", processing continues. If the response is "no", further processing cannot continue, and the I/O switch is closed. status_code = error_table_$unexpired_file This can occur only when the I/O switch is open for sequential_output. A file that must be extended, modified, or replaced is unexpired. The user is queried for permission to overwrite the unexpired file. If the response is "yes", processing continues. If the response is "no", further processing cannot continue, and the I/O switch is closed. status_code = error_table_$no_next_volume This can occur when reading a multivolume file, or when writing a file and reaching physical end of tape. The I/O module is unable to determine the name of the next volume in the volume set. The user is queried for permission to terminate processing. If the response is "yes", no further processing is possible. If the I/O switch is open for sequential_output, the I/O switch is closed. If the response is "no", the user is queried for the volume name of the next volume. (See status_code = 0 below.) status_code = 0 This occurs only when the response to the above query is "no". The user is requested to supply the name of the next volume. The response must be a volume name 6 characters or less in length, optionally followed by a mount message. Even if the volume name begins with a hyphen, it must NOT be preceded by the -volume control argument. If a mount message is to be specified, the response takes the following form: volume_name -comment STR where STR is the mount_message and need not be a contiguous string. See "Volume Specification" above. This is the only query that does not require a "yes" or "no" response. If a preset "yes" is supplied to all queries, this particular query never occurs. Structure Attribute Defaults: When a file is created, the I/O module can supply a default value for any or all of the file structure attributes. The defaults used are as follows: 1. record format - the default is F = vb 2. block length - the default is B = 8192 3. record length - F = u: undefined F = fb | f: R = block length F = vb | v: R = block length - 4 F = vbs | vs: R = 1044480 An injudicious combination of explicit specifications and defaults can result in an invalid attribute set. For example, if -record 12000 is specified, applying the defaults produces the following: -format vb -block 8192 -record 12000 This attribute set is invalid because, in vb format (see "Record Formats" below) the record length must be less than or equal to the block length minus 4. Overriding Structure Attributes: Normally, the -format, -block, and -record control arguments are not included in the attach description of an I/O switch that is opened for sequential_input; the structure attributes are extracted from the file labels. However, the I/O module permits the recorded structure attributes to be overridden by explicitly specified attach description control arguments. Because the apparent structure and characteristics of the file can be drastically altered, great care must be taken to ensure that attribute overrides do not produce unexpected and unwanted results. If a file has the following recorded attributes: -format fb -block 800 -record 80 an explicit specification of the -format fb and -record 800 control arguments causes each block of ten 80-character records to be treated as a single 800-character record. If a file has the following recorded attributes: -format fb -block 800 -record 80 an explicit specification of the -format fb, -block 80, and -record 80 control arguments causes the last 720 characters of every block to be discarded. No error is indicated, because every block of the file contains at least one 80-character record. Record Formats: Files are structured in one of four record formats: F(B), V(B), V(B)S, or U. When a file is created, its record format should be chosen in accordance with the nature of the data to be recorded. For example, data consisting of 80-character card images is most economically recorded in FB format, blocked fixed-length records. Data consisting of variable length text lines, such as PL/I source code produced by a text editor, is best recorded in VBS format, blocked spanned records, so that blanks are not inserted except after the last line. With the exception of U format, files are either blocked or unblocked, blocked being the usual case. Each block of an unblocked file contains just one record, whereas each block of a blocked file can contain several records. Blocking can provide a significant savings of processing time, because several records are accessed with a single physical tape movement. Furthermore, as blocks are separated by distances of blank tape, blocking reduces the amount of tape needed to contain a file. F(B) FORMAT: In F format, records are of fixed (and equal) length, and files have an integral number (N) of records per block. If the file is unblocked, N equals 1 and the record length (R) equals the block length (B). If the file is blocked, N > 1 and B equals (R * N) where N is known as the blocking factor. The Standard for F format records permits recording short blocks. A short block is a block that contains fewer than N records, when N is greater than 1. Although the I/O module can read this variant of F format, it writes a short block in only one case. The last block of a blocked file can contain fewer than N records if there are no more records to be written when the file is closed. Therefore, blocked F format files written by the I/O module are always in FBS (fixed blocked standard) format. There are two special cases in which a datum is padded out to length R. The first case is that of iobl (the number of characters to be written) equals 0: a record of R blanks is written. When such a record is subsequently read, it is interpreted as a record of R blanks, and NOT as a zero-length record. The second case is that of 0 < iobl > R: the record is padded on the right with blanks to length R, and the padded record written. When such a record is read, the original characters PLUS the padding are returned. The case of iobl greater than R is in error. V(B) FORMAT: In V format, records and therefore blocks may vary in length. Each record is preceded by a four-character record descriptor word (RDW) that contains the actual record length in binary, including the length of the RDW itself. Each block is preceded by a four-character block descriptor word (BDW) that contains the actual block length in binary, including the length of the BDW itself. V format files have an integral number of records per block, N. If the file is unblocked, B = R + 4; if blocked, B >= R + 4; For blocked records, the number of records per block varies indirectly with the size of the records. V(B)S FORMAT: In V(B)S format, a single record is formatted as one or more record segments. A record segment contains either a complete record, the initial portion of a record, a medial portion of a record, or the final portion of a record. No two segments of the same record can be contained in the same block, but a block may contain the segments of several different records. The maximum record length is limited only by the maximum size of a storage system segment, currently 1,044,480 characters. V(B)S format files have an integral number of record segments per block. If the file is unblocked, each block contains only one record segment; if blocked, the number of record segments per block is variable. In either case, R and B are independent of one another. Each record segment begins with a four-character segment descriptor word (SDW). The SDW contains a four-character record segment length in binary, that includes the length of the SDW itself. (See "DOS Files" above.) The SDW also contains a one-character record segment code in binary, that indicates if the segment contains a complete record, or an initial, medial, or final portion. U FORMAT: U format files contain records that do not conform to either F(B), V(B), or V(B)S format. A U format file is always unblocked. The record length is undefined, and the block length must equal or exceed the maximum record length. Blocks may vary in length. The special case of writing a record of less than 20 characters produces a block padded to length 20 with blanks. Volume Initialization: The Standard requires that all volumes be initialized with VOL1 and dummy HDR1 labels before they are used for output. The I/O module provides a semiautomatic volume initialization mechanism that performs this operation as an integral part of the output function. It should be noted that, as stated above, a newly initialized volume contains a dummy HDR1 label, but not a dummy file. If a file is created on a newly initialized volume without an explicit specification of the -number control argument, the I/O module attempts to append it to the file set, resulting in an error. Conformance To Standard: With one exception, the I/O module conforms to the Standard: the I/O module ignores the data set security field in the HDR1 label on input, and records it as 0 on output. Label Processing: VOL1 The label is processed on input and output. The owner-name and address-code-field, character positions (CP) 42 to 51, holds a three-character volume authentication code. UVL1 - UVL8 These labels are not written on output and ignored on input. HDR1/EOF1/EOV1 The labels are processed on input and output. The system-code-field, CP 61 to 73, is recorded as "MULTICS IBM ". HDR2/EOF2/EOV2 The labels are processed on input and output. The 17-character job/job-step-identification-field, CP 18 to 34, is recorded as follows: "MULTICS /" || Julian creation date || " " HDR3/EOF3/EOV3 - HDR8/EOF8/EOV8 These labels are not written on output and are ignored on input. UHL1/UTL1 - UHL8/UTL8 These labels are not written on output and are ignored on input. Error Processing: If an error occurs while reading, the I/O module makes 25 attempts to backspace and reread. If an error occurs while writing, the I/O module makes 10 attempts to backspace, erase, and rewrite. Should an error while reading or writing data prove to be unrecoverable, the I/O Module "locks" the file, and no further I/O is possible. (See reset_error_lock operation, below.) If an unrecoverable error occurs while writing file labels or tapemarks, the user is queried as to preserving the defective file versus file set consistency. (See "Queries" above.) If an unrecoverable error occurs during certain phases of volume switching or label reading, the I/O switch may be closed. The overriding concern of the error recovery strategy is: 1. to maintain a consistent file set structure. 2. to ensure the validity of data read or written. Close Operation: The I/O switch must be open. List of Control Orders: The I/O module supports eleven control operations. hardware_status retention status retain_none volume_status retain_all file_status reset_error_lock feov volume_density close_rewind In the descriptions below, info_ptr is the information pointer specified in an iox_$control call. Hardware_status Operation: This operation returns the 72-bit IOM status string generated by the last tape I/O operation. The I/O switch must be open. The substr argument (IOM_bits, 3, 10) contains the major and minor status codes generated by the tape subsystem itself. (See "MTS500 Magnetic Tape Subsystem", Order no. DB28 for an explanation of major and minor status.) The variable to which info_ptr points is declared as follows: declare IOM_bits bit(72) aligned; Status Operation: This operation returns a structure that contains an array of status codes, providing an interpretation of the IOM status string generated by the last tape I/O operation. These codes may be used in calls to the com_err_ subroutine, or may be converted to printable strings by calling the convert_status_code_ subroutine. (See the descriptions of the convert_status_code_ and the com_err_ subroutines.) The I/O switch must be open. The structure to which info_ptr points is declared in device_status.incl.pl1. Volume_status Operation: This operation returns a structure that contains the status of the current volume. If the I/O switch is open, the current volume is the volume on which the file section currently being processed resides. If the switch has never been opened, the current volume is the first (or only) volume in the volume set. If the switch was opened, but is now closed, the current volume is that on which the last file section processed resides. If the switch was closed by the I/O module as the result of an error while writing file header labels, trailer labels, or tapemarks, the current volume is the last (or only) volume in the volume set. The structure to which info_ptr points is declared in tape_volume_status.incl.pl1. In the current implementation of the I/O module, read_errors and write_errors are always zero. Eventually, the resource control package (RCP) supplies these values. File_status Operation: This operation returns a structure that contains the current status of the file specified in the attach description. If the I/O switch has never been opened, no information can be returned; this situation is indicated by tape_file_status.state = 0. If the switch was opened, but is now closed, the current status of the file is its status just prior to closing. If the switch was closed by the I/O module as the result of an error while writing file header labels, trailer labels, or tapemarks, the entire file may have been deleted. In this case, the structure contains the current status of the previous file in the file set, if any. The tape_file_status structure to which info_ptr points is declared in file_status.incl.pl1. The "event" referenced in tape_file_status.state above is defined as an error or circumstance that prevents continued processing of a file. For example, parity alert while reading, reached end of information, no next volume available, etc. Feov Operation: This operation forces end of volume (feov) when writing a file. The switch must be open for sequential output. The operation is equivalent to detection of the end of tape reflective strip. The info_ptr should be a null pointer. Close_rewind Operation: This operation specifies that the current volume is to be rewound when the I/O switch is next closed. info_ptr should be a null pointer. The switch need not be open when the operation is issued. The operation effects only one close; subsequent closings require additional control calls. Retention, Retain_none, Retain_all Operations: These operations cause the tape resources currently in use, i.e., tape drives(s) and tape volume(s), to be unassigned or retained at detach time according to the specified retention argument or operation. The info_ptr points to a fixed binary number with value as defined below: 1 retention -none or retain_none causes none of the tape resources currently in use to remain assigned at detach time. 2 retention -volume causes the tape volume(s) currently in use to remain assigned at detach time. 3 retention -device causes the tape drives(s) currently in use to remain assigned at detach time. 4 retention -all or retain_all causes all of the devices and volumes currently in use to remain assigned at detach time. Reset_error_lock Operation: This operation unlocks the files so that further I/O is possible subsequent to a parity-type I/O error while reading. Such an error is indicated by a previous iox_$read_record or iox_$position call having returned the status code error_table_$tape_error. In this case, the value of tape_file_status.event_lock is error_table_$tape_error. (See file_status operation, above.) The I/O switch must be open for sequential_input. The info_ptr should be a null pointer. NOTE: IF RECORDS ARE BLOCKED AND/OR SPANNED, THE VALIDITY OF ANY RECORDS READ SUBSEQUENT TO A PARITY-TYPE I/O ERROR IS NOT GUARANTEED. (The parity error is reported for the first read of a logical record in the block. The actual location of the error in the block in unknown.) Volume_density Operation: This operation returns the encoded density of the volume set. The I/O switch need not be open. The variable to which info_ptr points is declared as follows: declare volume_density fixed bin; The values returned and their meanings are listed below: -1 none specified yet 2 800 3 1600 4 6250 Detach Operation: The I/O switch must be closed. If the I/O module determines that the membership of the volume set may have changed, the volume set members are listed before the set is demounted; volumes not listed are available for incorporation into other volume sets. If the volume set is unlabeled, only the name of the last volume processed is listed. Position Operation: The I/O switch must be open for sequential_input. The I/O module does not support skipping backwards. In the course of a position operation, events or errors may occur that invoke the query mechanism. (See "Queries" above.) An unrecoverable error locks the file, and a severe error causes the I/O module to close the I/O switch. Read Length Operation: The I/O switch must be open for sequential_input. In the course of a read_length operation, events or errors may occur that invoke the query mechanism. (See "Queries" above.) An unrecoverable error locks the file, and a severe error causes the I/O module to close the I/O switch. Read Record Operation: The I/O switch must be open for sequential_input. Write Record Operation: The I/O switch must be open for sequential_output. Unlabeled Tapes: The I/O module supports basic processing of unlabeled tapes that are structured according to the "OS Tape Labels" document mentioned at the beginning of this description. DOS leading tape mark (LTM) unlabeled format tapes cannot be processed. The -no_labels control argument specifies that unlabeled tapes are to be processed. The -no_labels control argument and any of the following control arguments are mutually exclusive: -name -extend -replace -modify -expires -dos -force Volume switching is handled somewhat differently for unlabeled tapes. When the I/O module detects a tape mark in the course of an input operation, it determines whether or not any volumes remain in the volume sequence list. If another volume appears in the list, volume switching occurs and processing continues on the next volume. If the list is exhausted, the I/O module assumes that end of information has been reached. Detection of end of tape during an output operation is handled in much the same way as it would be for a labeled tape. (See the "OS Tape Labels" document for a complete description of unlabeled volume switching strategy.) Control Operations from Command Level: All control operations supported by this I/O module can be executed from command level by using the io_call command. The general format is: io_call control switchname operation -control_arg where: switchname is the name of the I/O switch that is attached through the I/O module to an IBM tape file-set. operation is any of the control operations previously described and summarized below. operation abbreviation control_arg --------- ------------ ----------- status st -all hardware_status hst reset_error_lock rel file_status fst volume_status vst retention ret -none, -volume, -device, -all retain_all reta retain_none retn close_rewind crw feov feov Control arguments: are operation control arguments valid only for the retention and the status operations. A control argument is required for the retention operation. -none causes none of the tape resources currently in use to remain assigned at detach time. -volume causes the tape volume(s) currently in use to remain assigned at detach time. -device -all causes all of the devices and volumes currently in use to remain assigned at detach time. The -all control argument is optional for the status operation. This control argument prints all available status information such as the device status, the volume status, the file status, and the hardware status. The -all control argument is only for use with the status operation through the io_call command. It is not defined for use in the status operation with iox_$control directly. ----------------------------------------------------------- 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