the file upon which the operation is to
take place. It consists of the keyword
FILE followed by a file expression enclosed
in parentheses.
Anexample of the FILE
option is shown in each of the statements
in this section.
INTO option
The INTO option can be used in the READ statement for any INPUT or UPDATE file.
The INTO option specifies a variable into which the logical record is to be read.
READ FILE (DETAIL) INTO (RECORD_1) ~
This specifies that the next sequential record is to be read into the variable RECORD_1.
Note that the INTO option can name an element string variable of varying length.
If the SCALARVARYING option of the
ENVIRONMENT attribute is specified for the file, then each record is assumed to
contain a two-byte prefix that specifies the length of the string data. (See -FROM Option- below).
If SCALARVARYING was not declared then, on input, the implementation calculates the string length from the record length and attaches i t as a two-byte prefix. For varying-length bit strings, this
calculation rounds up the length to a multiple of 8 and therefore the calculated length may be greater than the maximum declared length.
FROM Option
The FROM option must be used in the WRITE statement for any OUTPUT or DIRECT UPDATE file. It can also be used in the REWRITE statement for any UPDATE file. The FROM option specifies the variable from which the record is to be written.
Note that the FROM option can name an element string variable of varying length.
When using a WRITE statement with the FROM option, only the current length of a
varying-length string is transmitted to a data set, and a two-byte prefix specifying the length may be attached~ i t is attached only if the SCALARVARYING option of the ENVIRONMENT attribute is specified for the file.
Records are transmitted as an integral number of bytes. Therefore, if a bit string (or a structure that starts or ends with a bit string) that is not aligned on a byte boundary, is transmitted, the record will contain bits at the start or end that are not part of the string.
The FROM option can be omitted from a REWRITE statement for SEQUENTIAL BUFFERED UPDATE files. If the last record was read by a READ statement with the INTO option,
REWRITE without FROM has nO effect on the record in the data set~ but if the last record was read by a READ statement with the SET option, the record will be updated, in the buffer, by whatever aSSignments were made and copied back onto the ~ata set.
WRITE FILE (MASTER) FROM (MAS_REC);
REWRITE FILE (MASTER) FROM (MAS_REC);
Both statements specify that the value of the variable MAS REC is to be written into the file MASTER.- In the case of the WRITE statement, i t specifies a new record in a SEQUENTIAL OUTPUT file. The REWRITE statement specifies that MAS REC is to replace the last record read-from a SEQUENTIAL UPDATE file.
SET Option
The SET option can be used with a READ statement or a LOCATE statement. It specifies that a named pointer variable is to be set to point to the location in the buffer into which data has been moved during the READ operation, or which has been allocated by the LOCATE statement.
READ FILE (X) SET (P);
This statement specifies that the value of the pointer variable P is to be set to the location in the buffer of the next
sequential record. If the SET option is omitted, the pointer declared with the record variable will be set.
Note that if an element string variable of varying-length is transmitted, the SCALARVARYING option must be specified for the file.
IGNORE Option
The IGNORE option can be used in a READ statement for any SEQUENTIAL INPUT or SEQUENTIAL UPDATE file. It includes an expression whose integral value specifies a number of records to be skipped over and ignored. If the value of the expression is negative or zero, no records are skipped.
READ FILE (IN) IGNORE (3)~
This statement specifies that the next three records in the file are to be skipped.
If a READ statement has none of the options INTO, SET, and IGNORE, IGNORE (1) is
Chapter 12: Record-oriented Transmission 157
assumed.
KEY Option
The KEY option applies only to KEYED files associated with data sets of INDEXED,
I REGIONAL, or VSAM organization. (The types of data set organization applicable to record-oriented transmission are discu~sed
under -Data Set Organization-, later in this chapter.) The option consists of the keyword KEY followed by a parenthesized expression, which may be a character-string constant, a variable, or any other element expression: if necessary, the expression is evaluated and converted to a character string. The rules governing the length of the character string and what i t represents are discussed under "INDEXED Organization", I "REGIONAL Organization" , and "VSAM
Organization- later in this chapter.
The KEY option identifies a particular record. It can be used in a READ statement for an INPUT or UPDATE file, or in a
REWRITE statement for a DIRECT UPDATE file.
(The KEY option can be used in a READ
statement for a SEQUENTIAL file only if the associated data set has INDEXED or VSAM organi zation. )
READ FILE (STOCK) INTO (ITEM) KEY (STKEY);
This statement specifies that the record identified by the character-string value of the variable STKEY is to be read into
the variable ITEM.
KEYFROM and KEYTO Options
The KEYFROM and KEYTO options apply only to KEYED files associated with data sets of IINDEXED, REGIONAL, or VSAM organization, or
to TRANSIENT files. Each option consists of the keyword KEYFROM or KEYTO followed by an expression in parentheses. For KEYFROM, the expression may be a character-string constant, or any other element expression;
if necessary, the expression is evaluated and converted to a character string. For KEYTO, the expression must be a character-string variable or pseudovariable whose value is less than 256 bytes long. The rules governing the lengths of the
character strings and what they represent are discussed below, under -INDEXED
Organization-, "REGIONAL Organization", land ·VSAM Organization- (except for
TRANSIENT files, which are discussed under -Teleprocessing-).
158 OS PL/I CKT AND OPT LRM PART I
The KEYFROM option specifies a key that identifies the record on the data set, or
(for TRANSIENT files) the terminal to which the message or record is to be transmitted.
It can be used in a WRITE statement for a SEQUENTIAL OUTPUT or DIRECT UPDATE file or a DIRECT OUTPUT file that has REGIONAL organization, or in a LOCATE statement.
lIt can also be used in a WRITE statement Ifor a KEYED SEQUENTIAL UPDATE file
I associated with a VSAM data set.
WRITE FILE (LOANS) FROM (LOANREC) KEYFROM (LOANNO);
This statement specifies that the value of LOANREC is to be written as a record in the file LOANS, and that the character string value of LOANNO is to be used as the key with which i t can subsequently be
retrieved.
The KEYTO option specifies the name of the variable into which the key (or
terminal identifier, if the file is
TRANSIENT) of a record is to be read. I t can be used in a READ statement for a SEQUENTIAL INPUT, SEQUENTIAL UPDATE, or TRANSIENT INPUT file.
lIt can also be used in a WRITE statement Ifor a SEQUENTIAL OUTPUT or SEQUENTIAL IUPDATE file associated with a VSAM entry-Isequenced or relative-record data set.
READ FILE (DETAIL) INTO (INVTRY) KEYTO (KEYFLD);
This statement specifies that the next record in the file DETAIL is to be read into the variable INVTRY, and that the key of the record is be read into the variable KEYFLD.
EVENT Option
The EVENT option consists of the keyword EVENT followed by the name of an event variable in parentheses. (The appearance of a name in the EVENT option constitutes a contextual declaration of an event
variable.) The option can appear in any READ, WRITE, REWRITE, or DELETE statement for an UNBUFFERED file with CONSECUTIVE or REGIONAL organization or for any DIRECT file.
The EVENT option specifies that the input or output operation is to take place asynchronously (i.e., while other
processing continues) and that no I/O conditions (except for UNDEFINEDFILE) are raised until a WAIT statement, specifying the same event variable, is executed by the same task. For example:
READ FILE (MASTER) INTO (REC_VAR) EVENT (RECORD_i);
WAIT (RECORD_i);
When any expressions in the options of the READ statement have been evaluated, the input operation is started. As soon as this has happened, the statements following are executed. Any RECORD, TRANSMIT, KEY, or ENDFILE condition will not be raised until control reaches the WAIT statement.
If, when the WAIT statement is executed, the input operation is not complete, and if none of the four conditions is raised, execution of further statements is
suspended until the operation is complete.
When the operation is successfully
completed, processing continues with the next statement following the WAIT
statement. If any of the four conditions arise owing to execution of the READ
statement, the condition(s) will be raised when the WAIT statement is executed. For this implementation, only the conditions TRANSMIT and RECORD can occur together;
TRANSMIT is always processed first. Then, upon normal return from anyon-units
entered, processing continues with the next statement following the WAIT statement.
Although the EVENT option specifies
asynchronous processing, none of the four conditions can cause an interrupt until they are synchronized with processing by the WAIT statement.
Note that for consecutive and regional sequential files only one outstanding input/output operation is allowed for a file unless a higher number is specified in the NCP option of the environment attribute or DCB subparameter. The ERROR condition is raised if an attempt is made to initiate an input/output operation on a file in excess of the number allowed, while a previous input/output operation has not been waited for.
Once a statement containing an EVENT option has been executed, the event
variable named in the option is considered to be active: while i t is active, the same event variable cannot be specified again in an EVENT option. The event variable
becomes inactive again only after execution of the corresponding WAIT statement or when the file is closed.
The EVENT option can also be used with the CALL statement to specify asynchronous execution of procedures (see chapter 11,
"Multitasking"), and with the DISPLAY statement with the REPLY option.
NOLOCK Option
The NOLOCK option can be used in a READ statement that refers to an EXCLUSIVE file.
It specifies that the record accessed by the READ statement will not be locked between completion of a READ statement and commencement of the corresponding REWRITE;
the record will continue to be available to other tasks in addition to that which
issued the READ statement.