Chapter 5

Stream Input/Output

Stream I/O is one of the two general kinds of I/O performed by PL/I (the other is record I/O, described in Chapter 6, Record Input/Output). In stream I/O, more than one record or line can be processed by a single statement, and, conversely, multiple statements can process a single line or record. In record I/O, only one record of a file is processed by each READ or WRITE statement.

Stream input and output are performed by the statements GET and PUT, respectively. Both statements can perform either list-directed or edit-directed operations.

This chapter discusses the physical organization of stream files. See the Endless PL/I for OpenVMS Reference Manual for detailed information on the following topics:

The physical organization of stream files
The options and attributes applicable to stream I/O-the LINESIZE and PAGESIZE options and the PRINT and STREAM attributes
The statements used for stream I/O-GET, PUT, and FORMAT
The processing and positioning that take place during stream I/O operations
The format items and methods of combining them into format specifications for edit-directed stream I/O operations

A file has the STREAM attribute if one of the following conditions is met:

The file was declared explicitly with a DECLARE statement and the STREAM attribute.
The file was declared explicitly with a DECLARE statement and with neither the STREAM nor the RECORD attribute (as the default is STREAM).
The file was specified in and opened implicitly by a GET or PUT statement.

Files that are declared with the STREAM attribute have the following characteristics:

Sequential organization of records
Variable-length records, with the maximum length of either 132 (default) or the length defined by the LINESIZE option
When the attributes STREAM, OUTPUT, and PRINT appear in the same declaration, a fixed control area that contains formatting information for the output file.

Stream files contain only ASCII data. The ASCII format used to represent program data in a stream output file differs depending on the attributes given to the file. For example, the representation of character strings differs depending on the presence or absence of the PRINT attribute in the file declaration.

An existing stream file can be reopened and accessed by the READ and WRITE statements. If READ and WRITE open a file implicitly, the attributes RECORD INPUT SEQUENTIAL and RECORD OUTPUT SEQUENTIAL are implied, respectively. These attributes are compatible with, for example, an existing disk file created with the STREAM and OUTPUT attributes.

The most straightforward way to retrieve an entire line (record) from an existing stream file is with a simple READ statement. The following sample program uses the READ statement to retrieve entire lines from a stream file (TEST.STR) that was created by a previous program; each record is then output to a record file (TEST.REC). Note that both files are declared with the RECORD attribute to be compatible with the READ and WRITE statements. TEST.STR is assumed to have 80-character lines, and these input records are assigned to a varying-length character variable.

FILES: PROCEDURE OPTIONS(MAIN);

%REPLACE LENGTH BY 80;

DCL INFILE RECORD INPUT;
DCL OUTFILE RECORD OUTPUT;
DCL INSTRING CHAR(LENGTH) VARYING;
DCL EOF BIT(1) INITIAL('0'B);

      ON ENDFILE(INFILE) EOF='1'B;

      OPEN FILE(INFILE) TITLE('TEST.STR');
      OPEN FILE(OUTFILE) TITLE('TEST.REC');

      READ FILE(INFILE) INTO(INSTRING);
      DO WHILE(^EOF);
          WRITE FILE(OUTFILE) FROM(INSTRING);
          READ FILE(INFILE) INTO(INSTRING);
          END;

END FILES;

You can perform comparable operations with GET and PUT, working on existing files that were created with the RECORD attribute. Note, however, that the GET and PUT statements always access a file sequentially, regardless of the file's physical organization, and that all their input or output data is in ASCII characters. Some types of record files may also contain, in a single record, both ASCII program data and other ASCII data used to manipulate record files. If the file's records contain information other than program data, that information must be interpreted and processed by your program.