| Previous | Contents | Index |
An ON-unit is established for a specific ON condition or conditions following the execution of an ON statement that specifies the condition name(s). For example:
ON ENDFILE (ACCOUNTS) GOTO CLOSE_FILES; |
This ON statement defines an ON-unit for an ENDFILE (end-of-file) condition in the file specified by the name ACCOUNTS. The ON-unit consists of a single statement, a GOTO statement.
After an ON-unit is established by an ON statement for a condition, it remains in effect for the activation of the current block and all its dynamically descendant blocks, unless one of the following occurs:
ON OVERFLOW BEGIN . . . ON OVERFLOW BEGIN . . . END; END; |
An ON-unit can consist of a single simple statement, a group of statements in a begin block, or a null statement.
Simple Statements in ON-Units
The following ON statement specifies a single statement in the ON-unit:
ON ERROR GOTO WRITE_ERROR_MESSAGE;This ON statement specifies a GOTO statement that transfers control to the label WRITE_ERROR_MESSAGE in the event of the ERROR condition.
A simple statement must not be labeled and must not be any of the following:
DECLARE FORMAT RETURN DO IF SELECT END ON ENTRY PROCEDURE Begin Blocks in ON-Units
An ON-unit can also consist of a sequence of statements in a begin block. For example:
ON ENDFILE (SYSIN) BEGIN; CLOSE FILE (TEMP); CALL PRINT_STATISTICS(TEMP); END;This ON-unit consists of CLOSE and CALL statements that request special processing when the end-of-file condition occurs during reading of the default system input file, SYSIN.
If a BEGIN statement is specified for the ON-unit, the BEGIN statement must not be labeled. The begin block can contain any statement except a RETURN statement.
Null Statements in ON-Units
A null statement specified for an ON-unit indicates that no processing is to occur when the condition occurs. Program execution continues as if the condition had been handled. For example:
ON ENDPAGE(SYSPRINT);This ON-unit causes PL/I to continue output on a terminal regardless of the number of lines that have been output.
When a condition is signaled during the execution of a PL/I procedure, PL/I searches for an ON-unit to respond to the condition. This occurs unless you have used the SYSTEM option in an ON statement for the condition; the SYSTEM option causes the system default action to be executed regardless of the existence of any ON-unit.) PL/I first searches the current block, that is, the block in which the condition occurred. If no ON-unit exists in this block for the specific condition, it searches the block that activated the current block (its parent), and then the block that activated that block, and so on.
PL/I executes the first ON-unit it finds, if any, that can handle the
specified condition. If no ON-unit for the specific condition is found,
default PL/I condition handling is performed.
8.10.9 Completion of ON-Units
The ON-unit can complete its execution in any of the following ways:
Descriptions of each ON condition in this manual indicate the action that PL/I takes on completion of an ON-unit associated with the condition.
PL/I provides two distinct types of I/O processing, each of which handles input and output data in a different manner, and each of which has a unique set of I/O statements. These types of I/O are:
When a file is read or written with stream I/O, the data is treated as if it formed a continuous stream. Individual fields of data within the stream are delimited by commas, spaces, and record boundaries. A stream I/O statement specifies one or more fields to be processed in a single operation.
When a file is read or written with record I/O, however, a single record is processed upon the execution of an I/O statement.
This chapter describes I/O concepts that apply to both stream and
record I/O.
9.1 Opening and Closing Files
This section discusses the following:
A file declaration specifies an identifier, the FILE attribute, and one or more file description attributes that describe the type of I/O operation that will be used to process the file.
A file is denoted in an I/O statement by the FILE option as follows:
FILE(file-reference) |
file-reference
The name specified in the file's declaration. For example:
DECLARE INFILE FILE SEQUENTIAL INPUT; OPEN FILE(INFILE); |
Here, INFILE is the name of a file constant. A file constant is an identifier declared with the FILE attribute and without the VARIABLE attribute. Except for the default file constants SYSIN and SYSPRINT, all files must be declared before they can be opened and used.
By default, all file constants have the EXTERNAL attribute. Any
external procedure that declares the identifier with the FILE attribute
and without the INTERNAL attribute can access the same file constant
and, therefore, the same physical file.
9.1.2 File Variables
In PL/I, you can also refer to files using file variables and file-valued functions. For example:
DECLARE ANYFILE FILE VARIABLE; . . . ANYFILE = INFILE; OPEN FILE(ANYFILE); |
If INFILE is declared as in the previous example, the OPEN statement opens the file INFILE.
A file variable can also be given a value by receiving a file constant or variable passed as an argument, or by receiving a file constant or variable as the value of a function. For example:
GETFILE: PROCEDURE (PRINTFILE); DECLARE PRINTFILE FILE VARIABLE; |
This file variable is given a value when the procedure GETFILE is
invoked.
9.1.3 Opening a File
A file is opened explicitly by an OPEN statement or implicitly by a READ, WRITE, REWRITE, DELETE, PUT, or GET statement issued for a file that is not open.
The OPEN statement explicitly opens one or more PL/I files with a specified set of attributes that describe the file and the method for accessing it. The format of the OPEN statement is as follows:
FILE(file-reference)
A reference to the file to be opened. If the file is already open, the OPEN statement has no effect. Therefore, if you want to change any attributes of an open file, you should first close it, and then reopen it with the new attributes.file-description-attribute
The attributes and options of the file. The attributes specified are merged with the permanent attributes of the file specified in its declaration, if any. Then, default rules are applied to the union of these sets of attributes to complete the set of attributes in effect while the file is open.The attributes you can specify with the OPEN statement are as follows:
DIRECT ENVIRONMENT(option,...) RECORD INPUT SEQUENTIAL KEYED STREAM OUTPUT UPDATE The attributes are described in Chapter 2.
The OPEN options are described in Section 9.1.3.1.
DECLARE INFILE FILE,
STATE_FILE FILE KEYED;
OPEN FILE (INFILE),
FILE (STATE_FILE) UPDATE;
.
.
.
CLOSE FILE (STATE_FILE);
OPEN FILE (STATE_FILE) INPUT SEQUENTIAL;
|
The DECLARE and OPEN statements for INFILE do not specify any file description attributes; PL/I applies the default attributes STREAM and INPUT. If any statement other than GET is used to process this file, the ERROR condition is signaled.
The file STATE_FILE is declared with the KEYED attribute. With the first OPEN statement that specifies this file, it is given the UPDATE attribute and opened for updating; that is, READ, WRITE, REWRITE, and DELETE statements can be used to operate on records in the file. The KEYED attribute implies the SEQUENTIAL attribute; thus, records in the file can be accessed sequentially or by key.
The second OPEN statement specifies the INPUT and SEQUENTIAL attributes. During this opening, the file can be accessed by sequential and keyed READ statements; REWRITE, DELETE, and WRITE statements cannot be used.
DECLARE COPYFILE FILE OUTPUT;
OPEN FILE(COPYFILE) TITLE('COPYFILE.DAT');
|
The file specified by the file constant COPYFILE is opened for output.
Each time this program is run, it creates a new version of the file
COPYFILE.DAT.
9.1.3.1 OPEN Statement Options
The options that you can use in the OPEN statement are:
The LINESIZE option specifies the maximum number of characters that can be output on a single line when the PUT statement writes data to a file with the STREAM and OUTPUT attributes. The format of the LINESIZE option is:
LINESIZE(expression) |
expression
A fixed-point binary expression in the range 1 to 32767, giving the number of characters per line. If the expression is outside this range, a run-time error occurs.
The value specified in the LINESIZE option is used as the output line length for all subsequent output operations on the stream file, and it overrides the system default line size.
The default line size is as follows:
The line size is used by output operations to determine whether output will be placed on the current line or on the next line.
The PAGESIZE option is used in the OPEN statement to specify the maximum number of lines that can be written to a print file without signaling the ENDPAGE condition. The format of the PAGESIZE option is:
PAGESIZE(expression) |
expression
A fixed-point binary expression in the range 1 through 32767, giving the number of lines per page. If the expression is outside this range, a run-time error occurs.
The value specified in the PAGESIZE option is used as the output page length for all subsequent output operations on the print file, and overrides the system default page size. The default page size is the following:
During output operations, the ENDPAGE condition is signaled the first time that the specified page size is exceeded.
The PAGESIZE option is valid only for print files.
The TITLE option is specified in an OPEN statement to designate the external file specification of the file to be associated with the PL/I file. The TITLE option is specified only on the OPEN statement for a file. Its format is as follows:
TITLE(expression) |
expression
A character-string expression which represents an external file specification for the file.
For details on how the file specification is determined see the
Section 9.1.3.4.
9.1.3.2 Effects of Opening a File
Opening a file in PL/I has the following effects:
Each of these steps is described in more detail below. If an error
occurs during the opening of a file, the UNDEFINEDFILE condition is
signaled (see the Kednos PL/I for OpenVMS Systems User Manual.
9.1.3.3 Establishing the File's Attributes
The description attributes specified when a file is opened are merged with the file's permanent attributes. Duplicate specification of an attribute is allowed only for an attribute that does not specify a value.
An incomplete set of attributes is augmented with implied attributes. Table 9-1 summarizes the attributes that can be added to an incomplete set.
| Attribute | Implied Attributes |
|---|---|
| DIRECT | RECORD KEYED |
| KEYED | RECORD |
| STREAM OUTPUT | |
| SEQUENTIAL | RECORD |
| UPDATE | RECORD |
If the set of attributes is still not complete, PL/I uses the following steps to complete the set:
The completed set of attributes applies only for the current opening of
the file. The file's permanent attributes, specified in the declaration
of the file, are not changed.
9.1.3.4 Determining the File Specification
PL/I uses the value of the TITLE option to determine the file specification, that is, the actual name of the file or device on which the I/O is to be performed. The determination of the file specification depends on the following system-specific functions:
The rules for logical name translation and for the application of system defaults are described in detail in the Kednos PL/I for OpenVMS Systems User Manual.
The maximum length of the expanded file specification is 128.
9.1.3.5 Accessing an Existing File
A file opening accesses an existing file if the file specified by the TITLE option actually exists and if the following attributes are present:
Whenever PL/I accesses an existing file, the file's
organization is checked for compatibility with the PL/I attributes
specified. If any incompatibilities exist, the UNDEFINEDFILE condition
is signaled.
9.1.3.6 Creating a File
A file opening creates a new file if the following are all true:
You can specify the organization and record format of a new file with ENVIRONMENT options. If no ENVIRONMENT options are given, the new file's organization is determined as follows:
When a file is opened with the RECORD and OUTPUT attributes, only WRITE statements can be used to access the file. If the file has the KEYED attribute as well, the WRITE statements must include the KEYFROM option.
| Previous | Next | Contents | Index |