Input/Output Statement Options

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);

If program output has been suspended by Ctrl/o prior to execution of the PUT statement, the CANCEL_CONTROL_O option on the PUT statement cancels the effect of the Ctrl/o and outputs the data list.

This option can improve the speed of deletions when an indexed sequential file is updated.

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);

In this example, the OpenVMS file associated with the PL/I file OUTFILE will have a 2-byte fixed control area. Line numbers are assigned in increments of 100. Note that a file in this format, that is, a file that has CARRIAGE_RETURN_FORMAT carriage control (the default) and a 2-byte fixed control area, is handled in a special way by the OpenVMS system. When this file is printed with the DCL command PRINT or queued by the SPOOL option (as in this example), the contents of the fixed control area are printed to the left of each record on the output listing.

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.

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));

This READ statement obtains the record for the state whose population is greater than the value entered for the GET statement. For example, a value can be entered in response to this prompt as follows:

Population value: 8000000

In this case, the READ statement would read the first record in the index numbered 3 whose key value is greater than 8000000.

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: '));

Data entered in response to this GET statement is not displayed on the terminal.

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:

123DEL

If this data is entered in response to a GET statement that specifies the NO_FILTER option, the DEL key does not delete the last character typed (3); instead, it acts as the terminator of the input, just as the RETURN key usually does, and the value 123 is assigned to the input variable.

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.

Unlike a PUT statement followed by a GET statement, a GET statement with the PROMPT option is actually executed as a single statement. For example:

GET LIST (NUM) OPTIONS (PROMPT('Enter number: '));

When this statement is executed, the terminal display would be as follows:

Enter number: 44Return

The prompting string and the input data occur in the same statement.

On a terminal, using the PROMPT option provides the following benefits:

The PROMPT option causes any data that was not processed by the last GET operation to be ignored. If the SKIP option is not specified, the prompt is output at the current cursor position. If you specify the SKIP option in conjunction with the PROMPT option, the SKIP operation is performed before the prompting message is displayed.

When a command or program is being executed, the terminal keyboard accepts input data and stores it in a buffer called the type-ahead buffer. When the command or program is completed, the command interpreter reads its next command from the type-ahead buffer. When a GET statement is executed with this option in effect, any data in the type-ahead buffer is deleted, ensuring that the GET statement will not read any extraneous data.

The following example illustrates a record whose record identification is saved for later file access.

DECLARE
BOOKFILE FILE RECORD KEYED,
        INBUF CHARACTER(180) VARYING,
        SAVE_RECORD_ID(2) FIXED BINARY(31),
        KEYVALUE CHARACTER(10);
   ⋮
OPEN FILE(BOOKFILE) ENV(RECORD_ID_ACCESS);
READ FILE(BOOKFILE) INTO(INBUF) KEY(KEYVALUE)
          OPTIONS(RECORD_ID_TO(SAVE_RECORD_ID));
   ⋮
CLOSE FILE(BOOKFILE);
   ⋮
OPEN FILE(BOOKFILE) INPUT ENV(RECORD_ID_ACCESS);
READ FILE(BOOKFILE) INTO(INBUF) OPTIONS(
    RECORD_ID(SAVE_RECORD_ID));

During the first opening of the file, the record identification of a specified record is obtained and saved. When the file is subsequently reopened, this value is used to access a record and to effectively position the file at that record.

The TIMEOUT_PERIOD option prevents the WAIT_FOR_RECORD option from potentially causing an indefinite deadlock in the process.

In the following example, a 10-second waiting period is specified for a locked record. If the record is still locked after that period expires, an error is signaled.

READ FILE(DATAFILE) INTO (BUFFER)
   OPTIONS(WAIT_FOR_RECORD,TIMEOUT_PERIOD(10));

The WAIT_FOR_RECORD option can be used with the TIMEOUT_PERIOD option to avoid an indefinite wait.