| Previous | Contents | Index |
PL/I permits the specification of the OPTIONS keyword on I/O statements and supports certain options for each statement. This chapter explains how to code options for I/O statements, lists the valid options for each I/O statement, and describes each option individually.
An I/O statement option remains in effect only for the duration of the
statement on which it is specified. The only exception to this rule is
the INDEX_NUMBER option.
8.1 Option Format
I/O statement options are specified in a statement by the OPTIONS keyword and an options list. You enclose the options list in parentheses, and separate individual options by commas, as follows:
OPTIONS (option,... ; |
Following is an example of the I/O statement GET with three options, PROMPT, NO_ECHO, and PURGE_TYPE_AHEAD:
GET LIST (PASSWORD) OPTIONS (PROMPT('Enter password: '),
NO_ECHO,
PURGE_TYPE_AHEAD);
|
option(Boolean-expression) |
where Boolean-expression is a bit string of length 1,1B for true or 0B
for false. If no Boolean expression is specified and the option is
present in the option
list, the default value of true is supplied.
8.2 Summary of Input/Output Statement Options
Table 8-1 lists the I/O options, briefly describes their uses, indicates which statements they are valid for, and gives their data types.
| Option | Usage | Valid Statements | Data Type |
|---|---|---|---|
| CANCEL_CONTROL_O | Disables effect of Ctrl/o prior to terminal output. | PUT | BIT(1) |
| FAST_DELETE | Deletes a record without updating alternate indexes. | DELETE | BIT(1) |
| FIXED_CONTROL_FROM (variable) | Modifies the fixed control area of a record. |
REWRITE
WRITE |
Data type of fixed control area |
| FIXED_CONTROL_TO (variable) | Returns the contents of the fixed control area | READ | Data type of fixed control area |
| INDEX_NUMBER (expression) | Specifies the index to which an I/O operation applies. |
DELETE
READ REWRITE |
FIXED BINARY(31) |
| LOCK_ON_READ | Locks a record for reading and allows other readers but no writers. | READ | BIT(1) |
| LOCK_ON_WRITE | Locks a record for writing and allows other readers but no writers. | READ | BIT(1) |
| MANUAL_UNLOCKING | Specifies that the user, not RMS, is to control record locking and unlocking. | READ | BIT(1) |
| MATCH_GREATER | Matches any key with a value greater than the value of the KEY option. |
DELETE
READ REWRITE |
BIT(1) |
| MATCH_GREATER_EQUAL | Matches any key with a value greater than or equal to the value of the KEY option. |
DELETE
READ REWRITE |
BIT(1) |
| MATCH_NEXT | Matches any key with a value greater than the value of the KEY option. |
DELETE
READ REWRITE |
BIT(1) |
| MATCH_NEXT_EQUAL | Matches any key with a value greater than or equal to the value of the KEY option. |
DELETE
READ REWRITE |
BIT(1) |
| NO_ECHO | Suppresses display of input data on a terminal. | GET | BIT(1) |
| NO_FILTER | Suppresses recognition of Ctrl/u, Ctrl/r, and the DEL key on input operations. | GET | BIT(1) |
| NOLOCK | Disables record locking for the current operation. | READ | BIT(1) |
| NONEXISTENT_RECORD | Locks a nonexistent record. | READ | BIT(1) |
| PROMPT (expression) | Writes a prompting message prior to an input operation. | GET | CHAR(*) |
| PURGE_TYPE_AHEAD | Clears a terminal's type-ahead buffer before reading input data. | GET | BIT(1) |
| READ_REGARDLESS | Enables a record to be read regardless of any lock. | READ | BIT(1) |
| RECORD_ID (variable) | Accesses a record based on its internal identification. |
DELETE
READ REWRITE |
(2) FIXED BINARY(31) |
| RECORD_ID_TO (variable) | Returns the value of a record's internal identification. |
READ
REWRITE WRITE |
(2) FIXED BINARY(31) |
| TIMEOUT_PERIOD (expression) | Avoids a potential deadlock by indicating the number of seconds to wait before returning an error; used only with WAIT_FOR_RECORD. | READ | FIXED BINARY(31) |
| WAIT_FOR_RECORD | If a record is locked, causes the process to wait until it is available. | READ | BIT(1) |
The CANCEL_CONTROL_O option specifies, when the output device is a terminal, that the effect of Ctrl/o is disabled before data is output. This ensures that the beginning of the output list is displayed.
Use this option on a PUT statement that you want displayed regardless of whether previous output has been interrupted by Ctrl/o. By default, the Ctrl/o function remains in effect until another Ctrl/o. For example:
PUT SKIP LIST('Phase 1 complete... beginning phase 2...')
OPTIONS (CANCEL_CONTROL_O);
|
The FAST_DELETE option specifies, for a record in an indexed sequential file with alternate indexes, that only the current index for the file is to be updated.
The alternate index or indexes for the deleted record are not updated until the next time access is attempted to the record through an alternate index.
This option can improve the speed of deletions when an indexed
sequential file is updated.
8.2.3 FIXED_CONTROL_FROM Option
The FIXED_CONTROL_FROM option specifies a value to be written in the fixed control portion of a record in a file with variable-length records and a fixed control area. The format of the option is as follows:
FIXED_CONTROL_FROM (variable-reference) |
variable-reference
Specifies the variable associated with the fixed control area. The variable can be a scalar or a connected aggregate variable. It must not be an unaligned bit string or an aggregate consisting entirely of unaligned bit-string variables.
The following example illustrates writing a file with sequence numbers in a fixed control area:
DECLARE (OUTFILE,INFILE) FILE,
LINE_NUM FIXED BINARY(15), /* sequence numbers */
COPY_REC CHARACTER(132) VARYING,
EOF BIT(1) STATIC INIT('0'B);
OPEN FILE(INFILE) INPUT SEQUENTIAL;
ON ENDFILE(INFILE) EOF = '1'B;
OPEN FILE (OUTFILE) OUTPUT RECORD SEQUENTIAL
ENVIRONMENT (FIXED_CONTROL_SIZE(2));
READ FILE(INFILE) INTO(COPY_REC);
/* Increment sequence number; copy record to output file */
DO LINE_NUM = 100 BY 100 WHILE (^EOF);
WRITE FILE(OUTFILE) FROM (COPY_REC)
OPTIONS(FIXED_CONTROL_FROM (LINE_NUM));
READ FILE(INFILE) INTO(COPY_REC);
END;
CLOSE FILE (INFILE);
CLOSE FILE(OUTFILE) ENVIRONMENT (SPOOL);
|
The FIXED_CONTROL_TO option specifies that the contents of the fixed control area of a record in a file with a fixed control area are to be assigned to a specified variable. The format of the option is as follows:
FIXED_CONTROL_TO (variable-reference) |
variable-reference
Specifies the variable associated with the fixed control area. The variable can be a scalar or a connected aggregate variable. It must not be an unaligned bit string or an aggregate consisting entirely of unaligned bit-string variables.
The INDEX_NUMBER option specifies the particular index in an indexed sequential file to which a KEY option applies (primary index, secondary index, and so on). The format of this option is as follows:
INDEX_NUMBER (integer-expression) |
integer-expression
Specifies the index to be used. The value of the integer expression must be the number of an index for records in an indexed sequential file. The primary index is 0, the secondary index is 1, and so on.
The INDEX_NUMBER option on an I/O statement overrides the current index number, which can be set explicitly by the INDEX_NUMBER option of ENVIRONMENT or implicitly by a WRITE statement that specifies the KEY option or the RECORD_ID option.
When the INDEX_NUMBER option is used, the specified index becomes the current index for the file and is used in this and in all subsequent I/O operations until the INDEX_NUMBER option is again specified. For example:
GET LIST(BIRD) OPTIONS (PROMPT('Enter bird'));
READ FILE(STATEFILE) INTO(STATE) KEY(BIRD)
OPTIONS (INDEX_NUMBER(2));
|
In this example, the READ statement accesses the record in the file
STATEFILE using the index numbered 2.
8.2.6 LOCK_ON_READ Option
The LOCK_ON_READ option specifies a lock for reading that allows other readers but no writers. If you specify this option, then a record stream with a shared file that is open for reading only, is permitted to lock a record from modification by other programs or streams. Other streams are permitted to read the record but not to lock it.
The LOCK_ON_WRITE option specifies that a record will be locked for possible modifications. However, readers will be able to access the record. Streams that are locking records for modification can therefore allow nonlocking streams to read locked records.
The MANUAL_UNLOCKING option specifies that a record will be locked until it is explicitly unlocked by the process, thus giving you (instead of RMS) control over locking and unlocking.
The MATCH_NEXT option specifies that the record of interest is the first record whose key is greater than the key specified in the KEY option. MATCH_NEXT overrides the default rule for key matching, which is to look for an exact key match.
MATCH_GREATER is an obsolete synonym for MATCH_NEXT.
In the following example, STATE_FILE's third alternate key (that is, index number 3) is a fixed binary population value:
DECLARE 1 STATE,
2 NAME CHARACTER(20), /* Primary key */
2 POPULATION FIXED BINARY(31),/* index #3 */
2 CAPITAL,
.
.
.
SIZE FIXED BINARY(31),
STATE_FILE FILE RECORD INPUT KEYED SEQUENTIAL;
.
.
.
GET LIST(SIZE) OPTIONS(PROMPT(
'Population value: '));
READ FILE(STATE_FILE) INTO(STATE) KEY(SIZE)
OPTIONS(MATCH_NEXT,INDEX_NUMBER(3));
|
Population value: 8000000 |
The MATCH_NEXT_EQUAL option specifies that the record of interest is the record whose key matches the key specified in the KEY option or, if no match is found, the first record whose key is greater than the key specified.
MATCH_GREATER_EQUAL is an obsolete synonym for MATCH_NEXT_EQUAL.
The NO_ECHO option specifies, when the input device is a terminal, that the data entered at the terminal will not be displayed as it is entered.
This option is useful when data entered at a terminal is to be protected from being seen by users other than the one who entered the data. For example, if a password is to be entered, the NO_ECHO option protects the password, as follows:
GET LIST (PASSWORD) OPTIONS (NO_ECHO,
PROMPT('Enter Password: '));
|
The NO_FILTER option specifies, when the input device is a terminal, that the recognition of Ctrl/u, Ctrl/r, and the DEL key is to be suppressed. These characters are interpreted as terminators.
When NO_FILTER is in effect, the terminal keys that normally permit a user to edit data as it is entered do not perform their normal functions. For example:
123[DEL] |
The NOLOCK option specifies that a record accessed with a READ statement is not to be locked during the current operation.
The NOLOCK option can improve the speed of reading if it is used on a file that is opened with the ENVIRONMENT option SHARED_READ or with both SHARED_READ and SHARED_WRITE.
| Previous | Next | Contents | Index |