OPENING A FILE
1. OPEN FILE(MASTER);
2. OPEN FIlECOlDMASTER);
3. READ FIlECDETAIL) ... j
When statement number 1 is executed, the file name MASTER is taken to be the same as the ddname of a DD statement in the current job step. When statement number 2 is executed, the name OlDMASTE is taken to be the same as the ddname of a DD statement in the current job step. (The first 8 characters of a file name form the ddname. If OlDMASTER is an external name, it will be shortened by the compiler to OLDMTER for use within the
program.) If statement number 3 causes implicit opening of the file DETAIL, the name DETAIL is taken to be the same as the ddname of a DD statement in the current job step.
Chapter 4. Data Sets and Files 119
In each of the above cases, a corresponding DD statement must appear in the job stream; otherwise, the UNDEFINEDFILE condition would be raised. The three DD statements would appear, in part, as follows:
1. //MASTER DD 2. //OLDMASTE DD 3. //DETAIl DD
If the file reference in the statement which explicitly or implicitly opens the file is not a file constant, then the DD statement name must be the same as the value of the file
reference. The following example illustrates how a DD statement should be associated with the value of a file variable:
DCL PRICES FILE VARIABLE, RPRICE FILE;
PRICES = RPRICE;
OPEN FILECPRICES);
The DD statement should associate the data set with the file constant RPRICE, which is the value of the file variable PRICES, thus:
//RPRICE DD DSNAME= ...
Use of a file variable also allows a number of files to be manipulated at various times by a single statement. For example:
DECLARE F FILE VARIABLE, A FILE,
B FILE, C FILE;
DO F=A,B/C;
READ FILE (F)
... ,
END;
The READ statement is used to read the three files A, B, and C, each of which may be associated with a different data set. The files A, B, and C remain open after the READ statement has been executed in each instance.
The following OPEN statement illustrates use of the TITLE option:
OPEN FILE(DETAIL) TITLE('DETAILl');
If this statement were executed, there must be a DD statement in the current job step with DETAILl as its ddname. It might
appear, in part, as follows:
//DETAILl DD DSNAME=DETAILA, ...
Thus, the data set DETAILA is associated with the file DETAIL through the ddname DETAILI.
The file name can, at different times, represent entirely different data sets. In the above example of the OPEN statement, the file DETAILI is associated with the data set named in the DSNAME parameter of the DD statement DETAILI. If the file were closed and reopened, a TITLE option specifying a different ddname could be used, and then the file could be associated with a different data set.
120 OS PL/I Optimizing Compiler: Programmer's Guide
Use of the TITLE option allows you to choose dynamically, at open time, one among several data sets to be associated with a particular file name. Consider the following example:
DO IDENT='A', 'B', 'C';
OPEN FILE(MASTER)
TITLE('MASTER1'IIIDENT);
CLOSE FILECMASTER);
END;
In this example, when MASTER is opened during the first
iteration of the do-group, the associated ddname is taken to be MASTERlA. After processing, the file is closed, dissociating the file name and the ddname. During the second iteration of the do-group, MASTER is opened again. This time, MASTER is associated with the ddname MASTERIB. Similarly, during the final iteration of the do-group, MASTER is associated with the ddname MASTERlC.
ASSOCIATING SEVERAL FILES WITH ONE DATA SET
The TITLE option can be used to associate two or more PL/I files with the same external data set at the same time. This is
illustrated in the following example, where INVNTRY is the name of a DD statement defining a data set to be associated with two files:
OPEN FILE (FILEI) TITLE('INVNTRY');
OPEN FILE (FILE2) TITLE('INVNTRY');
If you do this, be careful. These two files access a common data set through separate control blocks and data buffers. When records are written to the data set from one file, the control information for the second file will not record that fact.
Records written from the second file could then destroy records written from the first file. PL/I does not protect against data set damage that might occur. If the data set is extended, the extension is reflected only in the control blocks associated with the file that wrote the data; this can cause an abend when other files access the data set.
CONCATENATING SEVERAL DATA SETS
Under OS, for input only, you can concatenate two or more
sequential or partitioned data sets (that is, link them so that they are processed as one continuous data set) by omitting the ddname from all but the first of the DD statements that describe them. For example, the following DD statements cause the data sets LISTl, LIST2, and LIST3 to be treated as a single data set for the duration of the job step in which the statements appear:
//GO.LIST DD DSNAME=LISTI,DISP=OLD // DD DSNAME=LIST2,DISP=OLD // DD DSNAME=LIST3,DISP=OLD
When read from a PL/I program, the concatenated data sets need not be on the same volume, but the volumes must be on the same type of device, and the data sets must have similar
characteristics (for example, block size and record format).
You cannot process concatenated data sets backward.
THE ENVIRONMENT ATTRIBUTE
The ENVIRONMENT attribute of the PL/I file declaration specifies information about the physical organization of the data set associated with a file, and other related information. The information is contained in a parenthesized option list; the syntax is:
~ Syntax
ENVIRONMENT(Option-list)
Abbreviation: ENV
The options may appear in any order, and are separated by blanks or commas.
The following example illustrates the syntax of the ENVIRONMENT attribute in the context of a complete file declaration (the options specified are for VSAM and are discussed in
Chapter 7, "Using VSAM Data Sets from PL/I" on page 222).
DCl FILENAME FILE RECORD SEQUENTIAL INPUT ENV(VSAM GENKEY);
Figure 45 on page 123 summarizes the ENVIRONMENT options and file attributes. Certain qualifications on their use are presented in the notes and comments for that figure. Those options that apply to more than one data set organization are described below. In addition, in the following chapters, each option is described with each data set organization to which it applies.
DATA SET ORGANIZATION OPTIONS
The options that specify data set organization are:
CONSECUTIVE INDEXED
REGIONAl({1 I 2 I 3}) TP({M I R})
VSAM
Each is described in the discussion of the data set organization it applies to.
If the data set organization option is not specified in the ENVIRONMENT attribute, a default is obtained when the file is opened:
• If the merged attributes from the DECLARE and OPEN statements do not include TRANSIENT, the default is CONSECUTIVE.
• If the attributes include TRANSIENT, the default is TPCM).
122 OS Pl/I Optimizing Compiler: Programmer's Guide
Record Key:
Record
124 OS PL/I Optimizing Compiler: Programmer's Guide
Direct
OTHER ENVIRONMENT OPTIONS
A constant or variable can be used with those ENVIRONMENT
options that require integer arguments, such as block sizes and record lengths. The variable must be unsubscripted,
unqualified, and have attributes FIXED BINARY(31,O) and STATIC.
Some of the information that can be specified in the options of the ENVIRONMENT attribute can also be specified, when TOTAL is not specified, in the subparameters of the DCB parameter of a DD statement. Figure 46 gives a list of equivalents.
ENVIRONMENT Option
Record format RECSIZE
BLKSIZE BUFFERS
CTLASAICTL360 NCP TRKOFL
KEYLENGTH KEYLOC ASCII BUFOFF
DCB Subparameter RECFMl
LRECL BLKSIZE BUFNO RECFM NCP RECFM KEYLEN RKP ASCII BUFOFF
1 VS must be specified as an ENVIRONMENT option, not in the DCB.
Figure 46. Equivalent ENVIRONMENT Options and DCB Subparameters
Record Format Options for Record-Oriented Data Transmission
Record formats supported depend on the data set organization.
~ Syntax
FtFBIFSIFBS1VIVBIVSIVBSIDIDBIU
Records can have one of the following formats:
Fixed-length F unblocked FB blocked
FS unblocked, standard FBS blocked, standard Variable-length V unblocked
VB blocked VS spanned
VBS blocked, spanned D unblocked, ASCII DB blocked, ASCII Undefined-length U (cannot be blocked)
When U-forrnat raccrds are read into a varying-length string, PL/I sets the length of the string to the block length of the retrieved data.
These record format options do not apply to VSAM data sets. If a record format option is specified for a file associated with a VSAM data set, the option is ignored.
VS-format records can be specified for data sets with consecutive or REGIONAL(3) organization only.
Record Format Options for stream-Oriented Data Transmission
RECSIZE Option
The record format options for stream-oriented data transmission are discussed in Chapter 5, "Defining Data Sets for Stream
Files" on page 134.
The RECSIZE option specifies the record length.
r=
SyntaxI
RECSIZECrecord-length)For files other than transient files and files associated with VSAM data sets, "record-length" is the sum of:
1. The length required for data. For variable-length and undefined-length records, this is the maximum length.
2. Any control bytes required. Variable-length records require 4, for the record length; fixed-length and undefined-length records do not require any.
For a transient file, it is the sum of:
1. The 4 V-format control bytes 2. One flag byte
3. Eight bytes for the key ( origin or destination identifier) 4. The maximum length required for the data
For VSAM data sets, the maximum and average lengths of the
records are specified to the Access Method Services utility when the data set is defined. If the RECSIZE option is included in the file declaration for checking purposes, the maximum record size should be specified. If RECSIZE is specified and conflicts with the values defined for the data set, the UNDEFINEDFIlE condition is raised.
The "record-length" can be specified as an integer or as a variable with the attributes FIXED BINARY(31,O) STATIC.
The value is subject to the following conventions:
Maximum:
Fixed-length, and undefined (except ASCII data sets):
32,760 bytes
V-format, and VS- and VBS-format with UPDATE files: 32,756 bytes
VS- and VBS-format with INPUT and OUTPUT files: no limit ASCII data sets: 9999
VSAM data sets: 32,761 for nonspanned records. For spanned records, the maximum is the size of the control area.
For VS- and VBS-format records longer than 32,756 bytes, the length must be specified in the RECSIZE option of ENVIRONMENT, and the DCB subparameter of the DD statement must specify lRECl=X.
126 OS Pl/I Optimizing Compiler: Programmer's Guide
BLKSIZE Option
Zero value:
A search for a valid value is made (in the following order) in the:
• DD statement for the data set associated with the file
• Data set label
If neither of these can provide a value, default action is taken (see "Record Format, BLKSIZE, and RECSIZE Defaults"
on page 129).
Negative Value:
The UNDEFINEDFILE condition is raised.
The BLKSIZE option specifies the maximum block size on the data set.
r-::
SyntaxBLKSIZE(blOCk-SiZe)
The "block-size" is the sum of:
1. The total lengthCs) of one of the following:
A single record
A single record and either one or two record segments Several records
Several records and either one or two record segments Two record segments
A single record segment
For variable-length records, the length of each record or record segment includes the 4 control bytes for the record or segment length.
The above list summarizes all the possible combinations of records and record segments options: fixed- or
variable-length blocked or unblocked, spanned or nonspanned.
When specifying a block size for spanned records, you must be aware that each record and each record segment requires 4 control bytes for the record length, and that these
quantities are in addition to the 4 control bytes required for each block.
2. Any further control bytes required. Variable-length blocked records require 4, for the block size; fixed-length and undefined-length records do not require any.
or
Any block prefix bytes required CASCII data sets only).
"block-size" can be specified as an integer, or as a variable with the attributes FIXED BINARYC3l,O) STATIC.
"block-size" is subject to the following conventions:
Maximum:
32,760 bytes Cor 9999 for an ASCII data set for which BUFOFF without a prefix-length value has been specified).
In regional 3 files, the maximum DECLAREd blocksize must not exceed 32,680 bytes. This is because the 32,760 byte maximum for blocksize consists of the declared blocksize plus the key length plus the length of the IOCB. If
'BLKSIZE=32760' is declared, when the keylength and IOCB length are added to it, the maximum will be exceeded and an
"UNDEFINED FILE" error message will be issued.
Zero value:
A search for a valid value is made (in the following order) in the:
• DD statement for the data set associated with the file
• Data set label
If neither of these can provide a value, default action is taken (see "Record Format, BLKSIZE , and RECSIZE Defaults"
on page 129) Negative value:
The UNDEFINEDFIlE condition is raised
The relationship of the "block-size" to the "record-length"
depends on the record format:
FB-format or FBS-format:
The block size must be a multiple of the record length VB-format:
The block size must be equal to or greater than the sum of:
1. The maximum length of any record 2. Four control bytes
VS-format or VBS-format:
The block size can be less than, equal to, or greater than the record length.
DB-format:
The block size must be equal to or greater than the sum ofl 1. The maximum length of any record
2. The length of the block prefix (if block is prefixed) Notes:
• The BlKSIZE option can be used with unblocked (F-, V-, or D-format) records, as follows:
The BLKSIZE option, but not the RECSIZE option, is specified. The record length is set equal to the block size (minus any control or prefix bytes), and the record format is unchanged.
Both the BlKSIZE and the RECSIZE options are specified, and the relationship of the two values is compatible with blocking for the record format used. The record format is set to FB, VB, or DB, whichever is
appropriate.
• If, for FB-format or FBS-format records, the block size equals the record length, the record format is set to F.
• For REGIONAL(3) data sets with VS format, record length cannot be greater than block size.
• The BLKSIZE option does not apply to VSAM data sets, and is ignored if it is specified for one.
128 OS PL/I Optimizing Compiler: Programmer's Guide
Record Format, BLKSIZE, and RECSIZE Defaults
BUFFERS Option
If, for a non-VSAM data set, either the record-format, BLKSIZE, or RECSIZE option is not specified, the following action is taken:
Record format:
A search is made in the associated DD statement or data set label. If the search does not provide a value, the
UNDEFINEDFILE condition is raised, except for files
associated with dummy data sets or the foreground terminal, in which case the record format is set to U.
Block-size or record-length:
If one of these is specified, a search is made for the other in the associated DD statement or data set label. If the search provides a value, and if this value is
incompatible with the value in the specified option, the UNDEFINEDFILE condition is raised. If the search is
unsuccessful, a value is derived from the specified option (with the addition or subtraction of any control or prefix bytes). If neither is specified, the UNDEFINEDFIlE
condition is raised, except for files associated with dummy data sets, in which case a "block-size" is set to 121 for F-format or U-format records and to 129 for V-format records. For files associated with the foreground terminal, the "record-length" is set to 120.
A buffer is a storage area that is used for the intermediate storage of data transmitted to and from a data set. The use of buffers can speed up processing of SEQUENTIAL files. Buffers are essential for the blocking and deblocking of records and for
locate-mode transmission.
The option BUFFERS(n) in the ENVIRONMENT attribute specifies, for CONSECUTIVE and INDEXED data sets, the number, n, of buffers to be allocated for a data set; this number must not exceed 255 (or such other maximum as was established at system generation).
~ Syntax BUFFERs(n)
If the number of buffers is not specified for a BUFFERED file or is specified as zero, two buffers are used by the optimizing compiler, and one buffer is used by the checkout compiler. A REGIONAL data set is always allocated two buffers.
In teleprocessing, the BUFFERS option specifies the number of buffers available for a particular message queue; that is, for a particular TRANSIENT file. The buffer size is specified in the message control program for the installation. The number of buffers specified should, if possible, be sufficient to provide for the longest message to be transmitted.
The BUFFERS option is ignored for VSAM; you use the BUFNI, BUFND, and BUFSP options instead.
GENKEV option--Key Classification
The GENKEY (generic key) option applies only to INDEXED and VSAM key-sequenced data sets. It enables you to classify keys
recorded in a data set and to use a SEQUENTIAL KEYED INPUT or SEQUENTIAL KEYED UPDATE file to access records according to their key classes.
r-::
SyntaxGENKEV
A generic key is a character string that identifies a class of keys; all keys that begin with the string are members of that class. For example, the recorded keys 'ABCD', 'ABCE', and 'ABDF' are all members of the classes identified by the generic keys 'A' and 'AB', and the first two are also members of the class 'ABC'; and the three recorded keys can be considered to be unique members of the classes 'ABCD', 'ABCE', and 'ABDF',
respectively.
The GENKEY option allows you to start sequential reading or updating of a VSAM data set from the first record that has a key in a particular class, and for an INDEXED data set from the first nondummy record that has a key in a particular class. The class is identified by the inclusion of its generic key in the KEY option of a READ statement. Subsequent records can be read by READ statements without the KEY option. No indication is given when the end of a key class is reached.
Although the first record having a key in a particular class can be retrieved by a READ with the KEY option, the actual key
cannot be obtained unless the records have embedded keys, since the KEYTO option cannot be used in the same statement as the KEY option.
In the following example, a key length of more than 3 bytes is assumed:
DCl IND FILE RECORD SEQUENTIAL KEYED UPDATE ENV (INDEXED GENKEY);
READ FILE(IND) INTO(INFIElD) KEY ('ABC');
NEXT: READ FILE (IND) INTO (INFIELD);
GO TO NEXT;
The first READ statement causes the first nondummy record in the data set whose key begins with 'ABC' to be read into INFIELD;
each time the second READ statement is executed, the nondummy record with the next higher key is retrieved. Repeated
execution of the second READ statement could result in reading records from higher key classes, since no indication is given
execution of the second READ statement could result in reading records from higher key classes, since no indication is given