The NONEXISTENT_RECORD option locks a randomly accessed record that does not exist in the file at the time of access. It prevents other streams from putting a new record into that cell until the stream that locked it either puts a record there itself or releases the record lock.

Rules

• The NONEXISTENT_RECORD option is valid only on a READ statement.
• This option applies only to relative files.
• This option remains in effect only for the current statement; then it is reset to false.

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

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 would be as follows:

Enter number: 44[Return]

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

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

• If the display of the prompting string is interrupted, for example, by a broadcast message, the entire string is redisplayed following the message that interrupted it.
• If Ctrl/u or Ctrl/r is entered in response to the prompt, the prompt message is repeated until data is entered.

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.

8.2.16 PURGE_TYPE_AHEAD Option

When the input device is a terminal, the PURGE_TYPE_AHEAD option specifies 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.

8.2.17 READ_REGARDLESS Option

The READ_REGARDLESS option allows a record to be read regardless of whether it is locked.

Rules

• The READ_REGARDLESS option is valid only on a READ statement.
• The READ_REGARDLESS option conflicts with the WAIT_FOR_RECORD option.
• If the record is not already locked, the READ_REGARDLESS option locks it.
• The READ_REGARDLESS option remains in effect only for the current statement; then it is reset to false.

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

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) FIXED BINARY(31), and it must be a connected array.

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 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.

8.2.19 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 as follows:

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 it 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.

The TIMEOUT_PERIOD option, used only with the WAIT_FOR_RECORD option, causes the waiting condition to continue only for the specified timeout period, in seconds. If the timeout period expires before the lock is granted, an error is signaled.

Rules

• The TIMEOUT_PERIOD option is valid only on a READ statement.
• If the TIMEOUT_PERIOD option is specified without the WAIT_FOR_RECORD option, it is ignored.
• The timeout period must be between 0 and 255 seconds.
• The TIMEOUT_PERIOD option remains in effect while the WAIT_FOR_RECORD option remains in effect, that is, for the current statement only.

Usage

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

8.2.21 WAIT_FOR_RECORD Option

The WAIT_FOR_RECORD option specifies that if a record is already locked, the process will wait until the record is available.

Rules

• The WAIT_FOR_RECORD option is valid only on a READ statement.
• The WAIT_FOR_RECORD option conflicts with the READ_REGARDLESS option.
• The WAIT_FOR_RECORD option remains in effect only for the current statement; then it is reset to false.

Usage

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

In addition to the PL/I input and output statements and the functions and features available through the options of the ENVIRONMENT attribute, there are also several built-in file-handling subroutines. These subroutines invoke Record Management Services (RMS) procedures. They are called built-in subroutines because you do not need to declare them before using them in a PL/I program. These subroutines are summarized in Table 9-1 and are described individually in the following sections.

Table 9-1 Summary of File-Handling Built-In Subroutines

Subroutine	Function
DISPLAY	Returns information about a file.
EXTEND	Allocates additional disk blocks for a file.
FLUSH	Requests the file system to write all buffers onto disk to preserve the current status of a file.
FREE	Unlocks all the locked records in a file.
NEXT_VOLUME	Begins processing the next volume in a multivolume tape set.
RELEASE	Unlocks a specified record in a file.
REWIND	Positions a file at its beginning or at a specific record.
SPACEBLOCK	Positions a file forward or backward a specified number of blocks.

9.1 DISPLAY Built-In Subroutine

The DISPLAY built-in subroutine returns information about a specified file. Its calling sequence is as follows:

CALL DISPLAY (file-reference,variable-reference);

file-reference

Specifies the file variable or constant for which information is to be obtained. If the file is not currently open, the DISPLAY subroutine implicitly opens the file with the attributes specified in the declaration of the file.

variable-reference

Specifies the name of a structure variable into which information about the file is to be placed.

The format of the data returned by DISPLAY is defined in the data structure PLI_FILE_DISPLAY. This structure is declared in the text module PLI_FILE_DISPLAY in the default INCLUDE library PLI$STARLET (the PL/I compiler searches this library by default when it compiles a PL/I program). Each member of PLI_FILE_DISPLAY contains, on return from a call to DISPLAY, a value associated with the file for which information is requested. To refer to a value, you refer to the corresponding member name in the structure. Tables 9-2 through 9-4 summarize the members of the structure as follows:

• Members containing information about the settings of ENVIRONMENT options
• Members containing information on file attributes
• Members containing information on device attributes

You declare the structure PLI_FILE_DISPLAY with the BASED attribute; thus, to use this variable you must also declare a pointer variable to reference the structure and use an ALLOCATE statement to allocate storage for it before calling DISPLAY. For example:

%INCLUDE PLI_FILE_DISPLAY; DECLARE STATE_FILE FILE RECORD KEYED, FILEPTR POINTER; OPEN FILE(STATE_FILE); ALLOCATE PLI_FILE_DISPLAY SET (FILEPTR); CALL DISPLAY (STATE_FILE,FILEPTR->PLI_FILE_DISPLAY);

Following this call to DISPLAY, you can reference any of the members of FILEPTR->PLI_FILE_DISPLAY to determine information about the file STATE_FILE. The following statements use the EXPANDED_TITLE field to display the expanded file specification of STATE_FILE and the INDEXED and NUMBER_OF_KEYS fields to display the number of keys in the file:

PUT SKIP EDIT('File',FILEPTR->EXPANDED_TITLE, 'opened for input') (A,X,A,X,A); IF FILEPTR->INDEXED THEN PUT SKIP EDIT ('It is indexed with',FILEPTR->NUMBER_OF_KEYS,'keys') (A,X,A,X,A);

If you do not use the structure PLI_FILE_DISPLAY, as shown in this example, you must provide a structure that has the same declaration as PLI_FILE_DISPLAY. To obtain a copy of PLI_FILE_DISPLAY, use the LIBRARY command. For example:

$ LIBRARY/TEXT/EXTRACT=PLI_FILE_DISPLAY/OUTPUT=FILESTRUC.PLI - $_SYS$LIBRARY:PLI$STARLET

Here, FILESTRUC.PLI is the name of the output file into which the LIBRARY command will copy PLI_FILE_DISPLAY.

Table 9-2 summarizes the values returned by DISPLAY that correspond to ENVIRONMENT options and the data type of each structure member. For information on ENVIRONMENT options, see Chapter 7.

Table 9-2 ENVIRONMENT Option Values Returned by DISPLAY

Member Name	Data Type of Value Returned	Meaning
APPEND	BIT(1)	APPEND option is enabled or disabled.
BACKUP_DATE	BIT(64) ALIGNED	Backup date of file (disk files only).
BATCH	BIT(1)	BATCH option is enabled or disabled.
BLOCK_BOUNDARY_FORMAT	BIT(1)	Records cannot cross block boundaries.
BLOCK_IO	BIT(1)	File is opened for block I/O.
BLOCK_SIZE	FIXED BIN	Block size of file (magnetic tape files only).
BUCKET_SIZE	FIXED BIN	Bucket size of file (disk files only).
CARRIAGE_RETURN_FORMAT	BIT(1)	Records have carriage return carriage control.
CONTIGUOUS	BIT(1)	CONTIGUOUS option is enabled or disabled.
CONTIGUOUS_BEST_TRY	BIT(1)	CONTIGUOUS_BEST_TRY option is enabled or disabled.
CREATION_DATE	BIT(64) ALIGNED	Creation date of file.
CURRENT_POSITION	BIT(1)	CURRENT_POSITION option is enabled or disabled.
DEFERRED_WRITE	BIT(1)	DEFERRED_WRITE option is enabled or disabled.
DELETE	BIT(1)	DELETE option is enabled or disabled.
EXPIRATION_DATE	BIT(64) ALIGNED	Expiration date of file.
EXTENSION_SIZE	FIXED BIN	Current extension size (disk files only).
FILE_ID	(6) FIXED BIN	File identification (disk files only).
FILE_SIZE	FIXED BIN	File allocation (disk files only).
FIXED_CONTROL_SIZE	FIXED BIN	Size of fixed-control area.
FIXED_LENGTH_RECORDS	BIT(1)	File has fixed-length records.
GROUP_PROTECTION	CHAR(4) VARYING	Protection for group members.
IGNORE_LINE_MARKS	BIT(1)	IGNORE_LINE_MARKS option is enabled or disabled.
INDEX_NUMBER	FIXED BIN	Current index number.
INDEXED	BIT(1)	File is or is not an indexed sequential file.
INITIAL_FILL	BIT(1)	INITIAL_FILL option is enabled or disabled.
MAXIMUM_RECORD_NUMBER	FIXED BIN	Relative file maximum relative record.
MAXIMUM_RECORD_SIZE	FIXED BIN	Largest record size.
MULTIBLOCK_COUNT	FIXED BIN	Multiblock count (disk files only).
MULTIBUFFER_COUNT	FIXED BIN	Multibuffer count.
NO_SHARE	BIT(1)	NO_SHARE option is enabled or disabled.
OWNER_GROUP	FIXED BIN	Group number of file's owner.
OWNER_MEMBER	FIXED BIN	Member number of file's owner.
OWNER_PROTECTION	CHAR(4) VARYING	Protection for file's owner.
RETRIEVAL_POINTERS	FIXED BIN	Number of mapping pointers.
PRINTER_FORMAT	BIT(1)	Records have printer carriage control.
READ_AHEAD	BIT(1)	READ_AHEAD option is enabled or disabled.
READ_CHECK	BIT(1)	READ_CHECK option is enabled or disabled.
RECORD_ID_ACCESS	BIT(1)	File is opened for access by record identification.
REVISION_DATE	BIT(64) ALIGNED	Revision date of file (disk files only).
REWIND_ON_CLOSE	BIT(1)	REWIND_ON_CLOSE option is enabled or disabled.
REWIND_ON_OPEN	BIT(1)	REWIND_ON_OPEN option is enabled or disabled.
SCALARVARYING	BIT(1)	SCALARVARYING option is enabled or disabled.
SHARED_READ	BIT(1)	SHARED_READ option is enabled or disabled.
SHARED_WRITE	BIT(1)	SHARED_WRITE option is enabled or disabled.
SPOOL	BIT(1)	SPOOL option is enabled or disabled.
SUPERSEDE	BIT(1)	SUPERSEDE option is enabled or disabled.
SYSTEM_PROTECTION	CHAR(4) VARYING	Protection for system users.
TEMPORARY	BIT(1)	TEMPORARY option is enabled or disabled.
TRUNCATE	BIT(1)	TRUNCATE option is enabled or disabled.
WORLD_PROTECTION	CHAR(4) VARYING	Protection for world users.
WRITE_BEHIND	BIT(1)	WRITE_BEHIND option is enabled or disabled.
WRITE_CHECK	BIT(1)	WRITE_CHECK option is enabled or disabled.

Table 9-3 summarizes the file attribute information returned by DISPLAY. All names in the table are level-2 members of the structure PLI_FILE_DISPLAY.

Table 9-3 File Attribute Information Returned by DISPLAY

Member Name	Type of Value Returned	Data Type of Meaning
COLUMN_NUMBER	FIXED BIN	Current column (stream output files only).
DIRECT	BIT(1)	File has or does not have DIRECT attribute.
EXPANDED_TITLE	CHAR(128) VARYING	Expanded file specification.
FILE_ORGANIZATION	CHAR(3)	SEQ, REL, or IDX.
FORTRAN_FORMAT	BIT(1)	File has or does not have FTN (ASA) carriage control.
INPUT	BIT(1)	File has or does not have INPUT attribute.
KEYED	BIT(1)	File has or does not have KEYED attribute.
LINE_NUMBER	FIXED BIN	Current line number (stream output files only).
LINESIZE	FIXED BIN	File's line size (stream output files only).
NUMBER_OF_KEYS	FIXED BIN	Number of keys (indexed sequential files only).
OUTPUT	BIT(1)	File has or does not have OUTPUT attribute.
PAGE_NUMBER	FIXED BIN	Current page number (PRINT files only).
PAGESIZE	FIXED BIN	Page size (PRINT files only).
PRINT	BIT(1)	File has or does not have PRINT attribute.
RECORD	BIT(1)	File has or does not have RECORD attribute.
SEQUENTIAL	BIT(1)	File has or does not have SEQUENTIAL attribute.
STREAM	BIT(1)	File has or does not have STREAM attribute.
UPDATE	BIT(1)	File has or does not have UPDATE attribute.

Table 9-4 lists the names of the structure members that contain information about the device to which a file is written or from which the file is to be read. All of the names in Table 9-4 are level-3 members of the structure PLI_FILE_DISPLAY; they each appear within the following minor structures, which have identical declarations:

• DEVICE
• SPOOLING_DEVICE