Chapter 6

Input/Output Statement Options

Note

The OPTIONS keyword is available in the dec and ansi dialects of Endless PL/I for POSIX Systems only.

PL/I lets you specify the OPTIONS keyword on input/output statements and supports certain options for each statement. This chapter explains how to code options for I/O statements, summarizes the valid options for each I/O statement, and describes each option individually.

6.1. Option Format

Use the OPTIONS keyword and an options list in a statement to specify I/O statement options. 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);

Any option that does not require an argument can be followed by a Boolean expression in the following format:

option(Boolean-expression)

where Boolean-expression is a bit string of length 1, '1'B for true or '0'B for false. If you specify the option in the option list and do not specify a Boolean expression, the default value of `true' is supplied.

6.2. Summary of Input/Output Statement Options

Table 6.1, “Summary of Input/Output Statement Options” lists the I/O options, their uses, the statements for which they are valid, and their data types.

Table 6.1. Summary of Input/Output Statement Options

Option	Usage	Valid Statements	Data Type
CANCEL_CONTROL_O ^[a]	Disables effect of CTRL/O prior to terminal output.	PUT	BIT(1)
FAST_DELETE ^[b]	Deletes a record without updating alternate indexes.	DELETE	BIT(1)
NO_ECHO	Suppresses display of input data on a terminal.	GET	BIT(1)
NO_FILTER	Sets UNIX raw mode (see stty(1) for more information)	GET	BIT(1)
PROMPT (expression)	Writes a prompting message prior to an input operation.	GET	CHAR(*)
PURGE_TYPE_AHEAD	Clears the terminal type-ahead buffer before reading input data.	GET	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)
^[a]Ignored; UNIX does not recognize Ctrl/O. ^[b]Ignored; RMS performance option.

6.2.1. NO_ECHO Option

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.

Rules

The NO_ECHO option is valid only on a GET statement.
This option is ignored if the input device is not a terminal.
This option remains in effect only for the current statement; then it is reset to false.

Usage

Use the NO_ECHO option when you want to keep data entered at a terminal from being seen by users other than the one who entered the data. For example, if you request a password, 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.

6.2.2. PROMPT Option

The PROMPT option specifies, when the input device is a terminal, a character-string prompt to be displayed before actual input. The format of this option is:

PROMPT (string-expression)

string-expression: Specifies a 1- to 254-character string expression.

Rules

The PROMPT option is valid only on a GET statement.
This option is meaningful only when the input device is a terminal.

Usage

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 will be as:

Enter number: 44 Return

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

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.

6.2.3. PURGE_TYPE_AHEAD Option

The PURGE_TYPE_AHEAD option specifies, when the input device is a terminal, that all data in the terminal's type-ahead buffer be deleted before the input operation is performed.

Rules

The PURGE_TYPE_AHEAD option is valid only on a GET statement.
This option is ignored if the input device is not a terminal.

Usage

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.

6.2.4. RECORD_ID Option

The RECORD_ID option indicates that the record of interest is specified by its record identification. The format of this option is:

RECORD_ID (variable-reference)

variable-reference

Specifies the name of a 2-element array variable containing the record identification.

The variable must be declared as (2) be connected.

Rules

The RECORD_ID option is valid on a READ, REWRITE, or DELETE statement.
RECORD_ID conflicts with the KEY option on the READ, REWRITE, or DELETE statement.
The file on which the operation is being performed must have been opened with the ENVIRONMENT option RECORD_ID_ACCESS.
If the file is an indexed sequential file, the RECORD_ID option resets the value of the current index number to 0.

Usage

The following example illustrates a record whose record identification is saved for a 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.

6.2.5. RECORD_ID_TO Option

The RECORD_ID_TO option specifies the name of a variable to be assigned the value of the record identification of the record on which the current operation is being performed. The format of this option is:

RECORD_ID_TO (variable-reference)

variable-reference

Is a reference to a 2-element array variable that will receive the value of the record's identification.

The variable must be declared as (2) FIXED BINARY(31) and must be connected.

Rules

The RECORD_ID_TO option is valid on the READ, WRITE, and REWRITE statements.
The file on which the operation is being performed must have been opened with the RECORD_ID_ACCESS option of the ENVIRONMENT attribute.