Chapter 7
File-Handling Built-In Subroutines
In addition to the PL/I input and output statements and the functions and features available through the options of the ENVIRONMENT attribute, there are also two built-in file-handling subroutines. They are called built-in subroutines because you do not need to declare them before using them in a PL/I program. The subroutines are:
FLUSH—Requests the file system to write all buffers onto disk to preserve the current status of a file
REWIND—Positions a file at its beginning
Both of these subroutines are valid only in the dec dialect.
The following sections describe the FLUSH and REWIND routines.
7.1. FLUSH Built-In Subroutine (DEC Dialect Only)
The FLUSH built-in subroutine writes all file buffers that have been modified and preserves all of the file attributes of the file. This subroutine provides the ability to checkpoint a file during its processing and ensure its integrity. Its calling sequence is:
CALL FLUSH (file-reference);file-referenceSpecifies the name of the file variable or file constant associated with the file whose buffers are to be flushed. If the file is not currently opened, the FLUSH subroutine performs no operation.
Use the FLUSH subroutine to explicitly request PLI to write all internal file buffers back to the file. This subroutine is called implicitly by the REWIND built-in subroutine.
The REWIND built-in subroutine positions a file so that the next record to be read will be the first record in the file. Its calling sequence is as follows:
CALL REWIND (file-reference);file-referenceSpecifies the name of the file constant or file variable associated with the file to be rewound. If the file is not currently open, the REWIND subroutine implicitly opens the file with the attributes specified in the declaration of the file.
Use this subroutine to begin processing a file at its logical beginning. This subroutine is valid for disk files of all organizations. The position of the file following the call to the REWIND subroutine is:
A sequential file is positioned at its first record.
A relative record file is positioned at the first occupied cell.
You can also use the REWIND built-in subroutine to reposition a stream file after an end-of-file condition. Normally, if end-of-file (Ctrl/D on a terminal) is entered during an input operation on a stream input file, the PL/I program must close the input file and reopen it before any more data can be read. However, an ENDFILE ON-unit can be written as:
ON ENDFILE(STREAMFIL) CALL REWIND(STREAMFIL);
This ON-unit calls the REWIND built-in subroutine each time an end-of-file is encountered for the file constant STREAMFIL. The REWIND built-in subroutine repositions the stream file at its beginning so that the program can continue reading input.