When PL/I opens a file, the initial positioning of the file depends on the type of file (record or stream), the access mode, and certain ENVIRONMENT options.

For a definition of the file-positioning information for record files, see Section 9.3.5. For a definition of file-positioning information for stream files, see Section 9.2.1.

9.1.4 File Description Attributes and Options

The file description attributes are summarized in Table 9-2. These attributes can be specified on DECLARE and OPEN statements.

Table 9-2 Summary of File Description Attributes

Attribute	Description
DIRECT	Records in the file will be accessed randomly.
INPUT	The file is an input file and will only be read.
KEYED	Records in the file will be accessed by key.
OUTPUT	The file is an output file and will only be written.
PRINT	The file will be output on a printer or terminal.
RECORD	The file will be accessed with record I/O statements.
SEQUENTIAL	Records in the file will be accessed sequentially.
STREAM	The file will be accessed with stream I/O statements.
UPDATE	The file will be accessed for both reading and writing, and records can be rewritten and deleted.

For detailed descriptions of these attributes, see Chapter 2.

9.1.5 Closing a File

The CLOSE statement dissociates PL/I files from the physical files with which they were associated when opened. The format of the CLOSE statement is as follows:

• CLOSE FILE(file-reference) [ENVIRONMENT(option,...)]
• [,FILE(file-reference) [ENVIRONMENT(option, ...)]]...;

FILE(file-reference)

A file to be closed. If the file is already closed, the CLOSE statement has no effect.

ENVIRONMENT(option,...)

One or more of the following ENVIRONMENT options, separated by commas:

BATCH
DELETE
REVISION_DATE
REWIND_ON_CLOSE
SPOOL
TRUNCATE

No other ENVIRONMENT options are valid. All ENVIRONMENT options are described in detail in the Kednos PL/I for OpenVMS Systems User Manual.

Examples

This CLOSE statement closes the file constant INFILE:

CLOSE FILE(INFILE);

This CLOSE statement closes two files specified in a comma list, each with a different ENVIRONMENT option:

CLOSE FILE(A) ENV(DELETE), FILE(B) ENV(REVISION_DATE(X));

Another example of a CLOSE statement is:

DECLARE STATE_FILE FILE KEYED; OPEN FILE(STATE_FILE) DIRECT UPDATE; . . . CLOSE FILE(STATE_FILE); OPEN FILE(STATE_FILE) INPUT SEQUENTIAL;

The file STATE_FILE is declared with the KEYED attribute. The first OPEN statement that specifies this file is given the DIRECT and UPDATE attributes and opened for updating; the file can be accessed only by key.

The CLOSE statement closes the file. The second OPEN statement specifies the INPUT and SEQUENTIAL attributes; the file can now be accessed sequentially.

9.2 Stream I/O

Stream I/O is one of the two general kinds of I/O performed by PL/I. Stream input and output is performed by the statements GET and PUT, respectively. Both statements can perform either list-directed or edit-directed operations.

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 contrast, record I/O only processes one record of a file in each READ or WRITE statement.

Table 9-3 summarizes the file description attributes and access modes for stream files.

Table 9-3 Attributes and Access Modes for Stream Files

Attributes Specified	Attributes Implied	Valid Devices and File Organizations	Usage
PRINT	STREAM OUTPUT	Any output device and any file except indexed	Individual data values are written with PUT statements that convert the values to character strings and automatically format the strings into lines, or records. A PUT statement can fill part or all of one or more lines. Data conversion and alignment within lines can use the default processing provided by the PUT LIST form of the PUT statement or can be explicitly controlled by format specifications in the PUT EDIT form of the PUT statement. The output fields can be aligned to specific tab positions. The PAGESIZE and LINESIZE options can be specified to control the formatting of lines on pages. The ENDPAGE condition is signaled when the end-of-page is reached.
STREAM INPUT		Any input device and any file except indexed	Individual data items are read by GET statements. A single GET statement can process all or part of one or more lines or records. The format of an input field can be determined by the default processing provided by the GET LIST form of the GET statement or can be explicitly controlled by format specifications in the GET EDIT form of the GET statement.
STREAM OUTPUT		Any output device and any file except indexed	This form of stream output is similar to that provided when PRINT is specified, except that tab positioning and page formatting are not provided. Moreover, when string values are written with the PUT LIST form of the PUT statement, they are enclosed in apostrophes. Files that are created with these attributes can be read back in with GET LIST statements when the file is opened with the STREAM and INPUT attributes.

Successive GET statements acquire their input from the same line or record until all the characters in the line have been read, unless the program explicitly skips to the next line. When necessary, a single GET statement will read multiple lines to satisfy its input-target list. A single input data item cannot cross a line unless it is a character string enclosed in apostrophes or unless the ENVIRONMENT option IGNORE_LINE_MARKS is in effect for the input file. This option produces stream input operations that match exactly with standard PL/I. However, the option is usually not necessary; most programs produce the expected results without it. (For more information on ENVIRONMENT, see the Kednos PL/I for OpenVMS Systems User Manual.

Successive PUT statements write their output to the same line or record until the line size is reached or until the program explicitly skips to a new line. A single PUT statement will write as many records as necessary to satisfy its output-source list. Any single data item that will not fit on the current line is split across lines.

The next sections describe the following aspects of stream I/O:

• Processing and Positioning of Stream Files
• Input by the GET statements.
• Output by the PUT statements.
• Format items
• Processing and Positioning of Character Strings
• Terminal I/O

A stream file is a file of ASCII text, divided into lines. For every stream file used in a program, PL/I maintains the following information:

• The locations of the beginning and end of the file. On input operations, the ENDFILE condition is signaled on the first attempt to read past the end of the file.
• For output files, the maximum number of ASCII characters in a line, or the line size. The line size is either a default value or the specific value you have established for the file (see Section 9.1 for LINESIZE option). The line size is used to determine when to skip to the next line. On input, a single data item cannot cross a line unless it is a character string enclosed in apostrophes or unless the file was opened with ENVIRONMENT (IGNORE_LINE_MARKS). On output, data items are continued on the next line.
• The current position in the file. Essentially, this is the point in the file at which the last input or output operation stopped. It is the exact character position at which the next output item is written or from which the next input item is read.

Input operations can begin at any position from the current position onward. The default is the current position. To acquire data from a different position, you can do the following:

• Use the SKIP option of the GET statement to advance by a specified number of lines before reading data.
• Use control format items to move to a specified position before reading data. With the GET statement, control format items are restricted to SKIP (the same operation as the SKIP option), COLUMN (advance to a specified character position), and X (advance by a specified number of character positions from the current position). Note that the control format items, unlike the SKIP option, are executed during, not before, the input of data. The control format items can signal the ENDFILE and ERROR conditions if the end-of-file is encountered.
• Close and then reopen the file, which sets the current position to the first character in the file.

Because stream files are sequential files, output operations always place data at the end of the file. You can do the following additional formatting of output with any stream output file:

• Use the SKIP option of the PUT statement to skip lines following the current position. If the current position is the beginning of a line, the SKIP option inserts null lines in the file between the current position and the position of the next output.
• Use the control format items to advance to a specified line or character position. The control format items are COLUMN (move to a specified character position), SKIP (the same effect as the SKIP option), and X (skip a specified number of characters following the current position). As with the input case, control format items are executed only during the output of data; if only part of the format list is used, the excess control format items are ignored.

If the output file is a print file (that is, has the attributes STREAM, OUTPUT, and PRINT, or is the default file SYSPRINT), the following additional information is maintained for the file:

• The current page number. The first output to a print file is written to page 1. The current page number is incremented by the PAGE option, the PAGE format item, and, in some circumstances, by the LINE option and LINE format item. You can evaluate the current page number for a specified print file with the PAGENO built-in function. You can also set it to a new value by assigning a value to the PAGENO pseudovariable.
• The page size. This is an integer that specifies the number of lines on a page. The page size is either the default value or the specific number that you have established for the print file (see Section 9.1). When the last line on a page is filled, the first attempt to write (or position the file) beyond that position signals the ENDPAGE condition. The ENDPAGE condition is signaled only on the first such attempt; if no ON-unit is established for the condition, a PUT PAGE is executed. For example, the ON-unit for the ENDPAGE condition can write a trailer at the bottom of the current page, or a header at the top of the next page, before printing a new page of data.
• The current line number. This is an integer specifying the line currently being used for output, relative to the top of the page. The first line on the page is line 1. The LINENO built-in function can evaluate the current line of a specified print file. The LINE option of the PUT statement, and the LINE format item, can reposition the file to a specified line.
• Position of tab stops. Tab stops always occur at 8-column increments on every line of a print file, beginning with column 1. The TAB format item can reposition a print file to a specified tab stop relative to the current position.

Terminals should always be declared as print files when used for output (see Section 9.2.6.)

9.2.2 Input by the GET Statement

The GET statement acquires data from an input stream, which is either a stream file or a character-string expression. The input file can be a file declared with the STREAM attribute or the default file SYSIN, usually associated with the user's default input device. See Section 9.2.6 for more information.

This section describes the syntax, options, and execution of GET statements.

9.2.2.1 Syntax Summary of the GET Statement

The GET statement has several forms; they are:

*Syntax elements common to two or more forms

input-target

The names of one or more variables to be assigned values from the input stream. Multiple input targets must be separated by commas.

An input target has one of the following forms:

reference

The reference is to a scalar or aggregate variable of any computational type. If the reference is to an array, data is assigned to array elements in row-major order. If the reference is to a structure, data is assigned to structure members in the order of their declaration.

(input-target,... DO reference=expression [TO expression]
[BY expression] [WHILE(expression)] [UNTIL(expression)])

Another form is:

(input-target,... DO reference=expression
[REPEAT expression] [WHILE(expression)] [UNTIL(expression)])

The input target can be any of these forms, and the references and expressions are as for the DO statement. Notice that the parentheses surrounding the input target are in addition to the parentheses surrounding the entire input list.

For a discussion of the matching of format items to input targets and of the use of DO specifications, see Section 9.2.4.13.

format-specification

A list of format items to control the conversion of data items in the input list. You can use data format items, control format items, or remote format items. For each variable name in the input-target list, there is a corresponding data format item in the format-specification list that specifies the width of the field and controls the data conversion. See Section 9.2.4 for format items.

FILE (file-reference)

An option specifying that the input stream is a file; the reference is to a declared file variable or constant. If neither the FILE option nor the STRING option is specified, PL/I assumes the file SYSIN. This file is associated with the default system input file SYS$INPUT.

If a file is specified and is not currently open, PL/I opens it with the attributes STREAM and INPUT. The UNDEFINEDFILE condition is signaled if the file cannot be opened.

SKIP [(expression)]

An option that advances the input file a specified number of lines before processing the input list. This option can be used only with the implied or explicit FILE option. If the expression is specified, it indicates the number of lines to be advanced; if it is omitted, the default is to skip to the next line. The SKIP option is always executed first, before any other input or positioning of the input file, regardless of its position in the statement.

OPTIONS (option,...)

An option that specifies one or more of the following options. This option can be used only with the default or explicit FILE option; it cannot be used with the STRING option. Multiple options must be separated by commas.

• CANCEL_CONTROL_O
• NO_ECHO
• NO_FILTER
• PROMPT (string-expression)
• PURGE_TYPE_AHEAD

The options are described fully in the Kednos PL/I for OpenVMS Systems User Manual.

STRING(expression)

An option specifying that the input stream is a character-string expression. The STRING option cannot be used with the FILE, OPTIONS, or SKIP option.

The GET STRING statement acquires a string from a character-string variable and assigns it to one or more input targets. If more than one input target is listed, the characters in the string should include any punctuation (comma or space separators or apostrophes) that would be required if the character string were in an external file.

The GET EDIT statement acquires fields of character-string data from an input stream, which can be a stream file or a character-string expression. The stream file can be a declared file or the default file SYSIN. GET EDIT converts the character strings under control of a format specification and assigns the resulting values to a specified list of input targets (variables). It also allows input of characters from selected positions in the input stream.

The form of the GET EDIT statement is as follows:

The syntax is described in more detail in Section 9.2.2.1.

Examples

GET EDIT (FIRST,MID_INITIAL,LAST) (A(12),A(1),A(20));

This statement reads the next 12 characters from the default stream input file (SYSIN) and assigns the string to FIRST. It then reads the next character into MID_INITIAL, and then the next 20 characters into LAST.

GET EDIT (SOCIAL_SECURITY) (A(12)) FILE (SOCIAL) SKIP (12);

This statement opens the stream file SOCIAL if the file was closed, advances 12 lines, reads the first 12 characters of the line, and assigns the characters to the variable SOCIAL_SECURITY.

GET EDIT (N, (A(I) DO I=1 TO N)) (F(4),SKIP,100 F(10,5));

where the dimension of A is less than or equal to 100. This reads the value of N from the input stream using the format item F(4). The process then skips to the next line (record). It reads N elements into the array A, using the format item F(10,5) for each element.

GET EDIT (NAME.FIRST,NAME.LAST) (A(10),X(3),A(20)) STRING('Philip A. Rothberg ');

This statement assigns <BIT_STRING>(Philip ) to the structure member NAME.FIRST, skips the middle initial, period, and space, and assigns <BIT_STRING>(Rothberg ) to NAME.LAST.

9.2.2.3 GET LIST

The GET LIST statement acquires character-string data from an input stream, which can be a stream file or a character-string expression. The stream file can be a declared file or the default file SYSIN. The acquired character strings are assigned to input targets named in the GET LIST statement, after being converted automatically to the targets' data types.

Use the GET LIST statement to read unformatted data from a stream file or character string. Because GET LIST does not require that data be aligned in specific columns, it is useful for acquiring input from a terminal.

The form of the GET LIST statement is as follows:

The syntax is described in more detail in Section 9.2.2.1.

Specifying Input Data

The items to be read into the input targets are separated by a space or a single comma. Multiple spaces are treated as a single space, and a comma can be surrounded by spaces. The following rules apply:

• No items can be split across lines unless the split occurs inside a quoted string.
• Character strings do not have to be enclosed in apostrophes unless they contain a space or comma or are written on more than one line. When a character string is enclosed in apostrophes, n apostrophes within the string are written as n * 2 apostrophes; for instance, the word isn't would be specified as either:

  isn't or 'isn''t'

• When a line begins with a comma or when two commas appear in the line without intervening nonspace characters, the item in the input-target list corresponding to that item is not updated. The target retains whatever value it contained before GET LIST was executed.
• Every input field, including the last input field in a line, must be terminated by a space, a comma, or a carriage return.
• Input fields are also terminated by the end-of-file (FILE option) or end-of-string (STRING option), unless the end is encountered inside a quoted string.
• If an input request from GET LIST encounters a null record, the null character string ('') is assigned, with appropriate conversion, to the corresponding input target. A null input record means a null record in a file or, if the input is from a terminal, a carriage return with no other input. See Section 9.2.6 for examples. ENVIRONMENT (IGNORE_LINE_MARKS) is used for the input file, record terminators such as the carriage return are ignored, and the GET LIST statement waits until the input request is satisfied.
• The CONVERSION condition is signaled whenever a data item in the stream cannot be converted to the data type of the corresponding item in the input-target list.
• The ENDFILE condition is signaled if the end of the file is encountered during file input. The ERROR condition is signaled if the expression in the STRING option does not contain enough characters to complete processing of the input-target list.

Examples

GETS: PROCEDURE OPTIONS(MAIN); DECLARE NAME CHARACTER(80) VARYING; DECLARE AGE FIXED; DECLARE (WEIGHT,HEIGHT) FIXED DECIMAL(5,2); DECLARE SALARY PICTURE '$$$$$$V.$$'; DECLARE DOSAGE FLOAT; DECLARE INFILE STREAM INPUT FILE; DECLARE OUTFILE PRINT FILE; GET FILE(INFILE) LIST(NAME,AGE,WEIGHT,HEIGHT,SALARY,DOSAGE); PUT FILE(OUTFILE) LIST(NAME,AGE,WEIGHT,HEIGHT,SALARY,DOSAGE); END GETS;

If the file INFILE.DAT contains the following data:

'Thomas R. Dooley',33,150.60,5.87,15000.50,4E-6,

then the program GETS writes the following output to OUTFILE.DAT:

Thomas R. Dooley 33 150.60 5.87 $15000.50 4.0000000E-06

In the input file (INFILE.DAT), the string <BIT_STRING>(Thomas R. Dooley) is surrounded by apostrophes so that the spaces between words will not be interpreted as field separators.

GSTR: PROCEDURE OPTIONS(MAIN); DECLARE STREXP CHARACTER(80) VARYING; DECLARE (A,B,C,D,E) FIXED; DECLARE OUTFILE STREAM OUTPUT FILE; OPEN FILE(OUTFILE) TITLE('GSTR.OUT'); STREXP = '1,2,3,4,5'; GET STRING(STREXP) LIST(A,B,C,D,E); PUT FILE(OUTFILE) LIST(A,B,C,D,E); END GSTR;

The program GSTR writes the following output to GSTR.OUT:

1 2 3 4 5

For other examples, see Section 9.2.6.