INPUT/OUTPUT OPERATIONS

Input and output using files may be done either asindexedoperations or assequentialoperations.

An indexed operation uses a line number to directly access a specific line. A sequential operation accesses the first line or the next line following the previous line that was read or written. Many devices, such as card readers and line printers, are intrinsically sequential. For these devices, indexed operations are not defined. Similarly, indexed operations have no meaning for a file whose organization is sequential.

The type of operation used for input and output depends on the setting of a pair of I/O modifier bits.

These bits specify whether the operation is to be indexed or sequential. These bits may be set either by the SEQUENTIAL (S) or INDEXED (I) FDname modifiers or by the corresponding I/O modifier bits on an input/output subroutine call. The complete details of I/O modifier bit processing are given in Appendix A to this section.

For all input or output operations withlinefiles, the system maintains acurrent line pointerthat points just past the last record read or written, and acurrent line numberthat contains the line number of the last record read or written. When a sequential I/O operation is initiated, the current line pointer is used to determine the record that is to be read or written. After the operation has been completed, the current line pointer is set just past the line that was read or written. If the I/O operation is done in the backwards direction, the line pointer is set just before the line that was read or written (i.e., just past the line going in the backwards direction). In addition, the current line number is updated.

The BKWD FDname modifier, the sign of the increment specified in a line-number range, and the BKWD I/O modifier bit specified on an I/O subroutine call interact to determine the direction of an I/O operation. The BKWD FDname modifier and the sign of the increment determine a direction for the subset of the file specified by the line-number range. The rules for determining this direction are given in the section “Line-Number Ranges.” If the direction is forwards, the I/O operation is done in the forwards direction; if the direction is backwards, the I/O operation is done in the backwards direction.

The setting of the BKWD I/O modifier bit on an I/O subroutine call may be used to further control the direction of the I/O operation. If the BKWD modifier bit is set, the direction of the operation is reversed. The following table illustrates the use of these modifiers in controlling the direction of the I/O operation.

BKWD I/O Direction of FDname Specification Modifier Bit I/O Operation

A(1,10) 0 Forwards

If the I/O modifier bits specify a sequential operation or if they specify neither a sequential nor an indexed operation (the default), a sequential operation is performed.

A sequential operation specifies that the “next” record is to be read or written. The “next” record is determined by the value of the current line pointer. The setting of the BKWD I/O modifier bit indicates whether “next” is taken in the ascending or descending order. If the modifier bit is not set and the direction of the subset is forwards, ascending order is used; if the modifier bit is set and the direction of the subset is forwards, descending order is used. For a read operation, “next” means the record follows in ascending (descending) line number order from the current value of the line pointer.

If an increment is explicitly given with the FDname, the line read is the first line in the file past the current line pointer that has a line number which is a multiple of the increment from the beginning line number. For a write operation, “next” means the first line number past the current line pointer that is a multiple of the increment from the beginning line number. If no increment is specified, a default of 1 is used for write operations.

For a sequential read operation with a line file, the line-number range determines which lines of the file may be read. The read operation begins with the beginning line number “b”. If “b” is omitted, line number 1 is used. Note that this is not necessarily the first line of the file. All lines in the subset of the file as specified by the line-number range may be read. Any lines not in the subset, even if they are between the beginning line number and the ending line number, are not read (i.e., they are skipped).

If an attempt is made to read a line in the subset which does not exist in the file, reading continues with the next line in the subset. For example, the command

LIST A(10,20,2)

initiates read operations for lines 10, 12, 14, 16, 18, and 20 from line file A. Each line of this subset that exists in the file is listed. Lines in the subset that do not exist in the file and all other lines in the file that are not in the subset defined by (10,20,2) are not listed.

If a sequential read operation is not the first I/O operation on a line file (e.g., if an indexed read or any write operation was the last operation completed), the line read is the first line past the current line pointer in the appropriate direction that has a line number that is a multiple of “i” past the beginning line number “b”.

For a sequential write operation to a line file, the line-number range determines which lines of the file may be written. The first line written is the beginning line number “b”. If “b” is omitted, line number 1 is used. All lines in the subset of the file as specified by the line-number range may be written. Any lines not in this subset, even if they are between the beginning line number and the ending line number, are not changed. If an attempt is made to write to a line not in the subset, an end-of-file condition is generated. For example, the command

COPY *SOURCE* A(10,20,2)

reads 6 lines from *SOURCE* and writes them to lines 10, 12, 14, 16, 18, and 20 of file A. Any other lines in the file that are not in the subset defined by (10,20,2) are not changed. When an attempt is made to write a seventh line, an end-of-file occurs.

Indexed Operations with Line Files

An indexed operation is performed if the I/O modifier bits specify an indexed operation.

For an indexed operation, a line number must be given which specifies the line to be read by a read operation or the line to be written by a write operation. The line-number range specified on the FDname is checked to determine whether the given line number is in the subset of the file that may be read or written. If the line is not within this subset or the line contains the “$ENDFILE” delimiter, an end-of-file condition occurs. The rules for defining the subset of the file specified by the line-number range are given in the earlier section “Line-Number Ranges.” After an indexed operation is completed, the current line pointer and the current line number are updated. The current line pointer will point after (in the direction of the subset of the file) the line read or written unless the BKWD modifier was specified on the I/O call, in which case it will point before the line read or written.

Implicit concatenation with indexed operations is handled as follows. For an indexed read operation, if the line selected is a “$CONTINUE WITH” line and implicit concatenation is enabled, the concatenation will occur and the same line number will be used to read the new file or device specified by the FDname in the implicit concatenation line.

Indexed operations are not allowed with sequential files unless the SEQFCHK option is OFF. An error comment will be generated if an indexed operation is specified with an FDname; a return code of 20 will be given if an indexed operation is attempted with a sequential file in an I/O subroutine call.

Sequential Operations with Sequential Files and Devices

For I/O operations involving sequential files or devices, the test to determine whether a given line is in the subset specified by the line-number range is the same as for line files. However, since lines in a sequential file or device have no line numbers inherently associated with them, the system “generates”

line numbers internally using the beginning line number and the increment specified by the user and tests if the result exceeds the ending line number. The data lines can only be read or written sequentially, either forwards or backwards (depending on the inherent nature of the file or device).

Just as the current line pointer is maintained for line files, a current read pointer and a current write pointer are maintained for sequential operations on sequential files. In general, these two pointers are independent of each other, i.e., the read pointer controls only read operations and the write pointer controls only write operations. The read pointer initially points before the first line of the file and the write pointer initially points after the last line of the file. These pointers are updated appropriately after a sequential read or write operation to point to the next line to be read or written.

For a sequential read operation, the read pointer may move either forwards or backwards depending on the setting of the BKWD I/O modifier bit.

For a sequential read operation from a sequential file or device, the line read is the next line after the current position of the read pointer in the appropriate direction or the line at the current position of the device (e.g., the current position of a magnetic tape or card reader).

For a sequential write operation to a sequential file or device, the line written is the next line after the current position of the write pointer (thus, new lines are always written at the end of the file, by default), or the line at the current position of the device (e.g., the current position of a magnetic tape or line printer). If the write pointer does not point to the end of the file, a sequential write operation will truncate the remainder of the file after the line written unless the SP modifier is specified (see below).

For sequential files, a beginning line number other than 1 is not allowed unless the SEQFCHK option is OFF. For devices, any beginning line number is legal.

The read and write pointers may be explicitly positioned to a particular line in a sequential file via the NOTE and POINT subroutines. This is further described in Appendix B to this section.

The SP Modifier with Files

The SP (SPECIAL) modifier is a file- or device-dependent modifier that may be used to further control I/O operations. Only the use of SP as applied to I/O operations with files is described here.

For details on using SP with terminals operating through the UMnet/Michnet Computer Network, see the appropriate sections ofMTS Volume 4: Terminals and Networks in MTS, Reference R1004, and MTS Volume 19: Magnetic Tapes in MTS, Reference R1019.

For read operations to both line files and sequential files, the SP modifier is used to skip to the next line without transmitting data. The current line number and current line pointer (or read pointer for sequential files) are updated. However, no data is read into the buffer provided by the I/O subroutine and a zero is returned for the length of the line read.

For write operations to sequential files, the SP modifier is used to replace the current line without truncating the file. The line at the current position of the write pointer is replaced by a new line. If the new line is shorter than the current line, it is padded on the right with blanks; if the new line is longer than the current line, it is truncated to the length of the current line. In either case, an error message is generated. If the write pointer is at the end of the file, no write operation is performed and an error message is generated. The SP modifier is ignored for write operations to line files.

Explicit Concatenation with I/O Operations

The processing of the next member of an explicit concatenation is started whenever an end-of-file occurs for a read or write operation unless the NOEC modifier was specified. This occurs when the physical end of the file or device is encountered or when the line number specified for the operation is not within the subset of the file specified by the line-number range. Specifying NOEC inhibits the

transfer to the next member of the explicit concatenation.

For an indexed read operation, an end-of-file returned to the program (when NOEC is not specified) indicates that none of the members of the concatenation contains the line specified for the indexed operation. A successful indexed read operation selects the specified line from the first member of the concatenation that contains that line.

For a sequential write operation, the line-number range specifications may be used to control the flow of data into several files or devices. For example,

COPY A B(1,10)+*SINK*(1,10)+B(11)

copies from file A (starting at line 1) 10 lines into line file B (starting at line 1), followed by 10 lines to

*SINK*, followed by the remainder of file A into file B (starting at line 11).

If the file that is a member of an explicit concatenation is unable to expand during a write operation, the write operation transfers to the next member of the concatenation to write the line.