You can use various options in the ENVIRONMENT attribute. Each type of file has different attributes and environment options, which are listed below.
You use the ENVIRONMENT attribute of a PL/I file declaration file to specify information about the physical organization of the data set associated with a file, and other related information. The format of this information must be a parenthesized option list.
>>-ENVIRONMENT--(--option-list--)------------------------------><
Abbreviation: ENV
You can specify the options in any order, 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 Defining and using VSAM data sets).
DCL FILENAME FILE RECORD SEQUENTIAL
INPUT ENV(VSAM GENKEY);
Table 13 summarizes the ENVIRONMENT options and file attributes. Certain qualifications on their use are presented in the notes and comments for the figure. Those options that apply to more than one data set organization are described in the remainder of this chapter. In addition, in the following chapters, each option is described with each data set organization to which it applies.
|
Data set type |
S t r e a m |
Record |
Legend:
|
||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
File Type |
C o n s e c u t i v e |
Sequential |
Direct |
||||||||
|
Consecutive |
T e l e p r o c e s s i n g |
I n d e x e d |
V S A M |
R e g i o n a l |
I n d e x e d |
V S A M |
|||||
|
B u f f e r e d |
U n b u f f e r e d |
R e g i o n a l |
|||||||||
|
File attributes1 |
Attributes implied |
||||||||||
|
File |
I |
I |
I |
I |
I |
I |
I |
I |
I |
I |
|
|
Input1 |
D |
D |
D |
D |
D |
D |
D |
D |
D |
D |
File |
|
Output |
O |
O |
O |
O |
O |
O |
O |
O |
O |
O |
File |
|
Environment |
I |
I |
I |
S |
S |
S |
S |
S |
S |
S |
File |
|
Stream |
D |
- |
- |
- |
- |
- |
- |
- |
- |
- |
File |
|
Print1 |
O |
- |
- |
- |
- |
- |
- |
- |
- |
- |
File stream output |
|
Record |
- |
I |
I |
I |
I |
I |
I |
I |
I |
I |
File |
|
Update |
- |
O |
O |
O |
- |
O |
O |
O |
O |
O |
File record |
|
Sequential |
- |
D |
D |
D |
- |
D |
D |
- |
- |
D |
File record |
|
Buffered |
- |
D |
- |
- |
I |
D |
D |
- |
- |
S |
File record |
|
Keyed2 |
- |
- |
- |
O |
I |
O |
O |
I |
I |
O |
File record |
|
Direct |
- |
- |
- |
- |
- |
- |
S |
S |
S |
S |
File record keyed |
|
|
|
ENVIRONMENT options |
Comments |
||||||||||
The options that specify data set organization are:
>>-+-CONSECUTIVE-------+--------------------------------------->< +-INDEXED-----------+ +-REGIONAL--(--1--)-+ '-VSAM--------------'
Each option is described in the discussion of the data set organization to which it applies.
You can use a constant or variable with those ENVIRONMENT options that require integer arguments, such as block sizes and record lengths. The variable must not be subscripted or qualified, and must have attributes FIXED BINARY(31,0) and STATIC.
The list of equivalents for ENVIRONMENT options and DCB parameters are:
Record formats supported depend on the data set organization.
>>-+-F---+----------------------------------------------------->< +-FS--+ +-FB--+ +-FBS-+ +-V---+ +-VS--+ +-VB--+ +-VBS-+ '-U---'
Records can have one of the following formats:
|
Fixed-length |
F FB FS FBS |
unblocked blocked unblocked, standard blocked, standard |
|
Variable-length |
V VB VS VBS |
unblocked blocked spanned blocked, spanned |
|
Undefined-length |
U |
(cannot be blocked) |
When U-format records 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 you specify a record format option for a file associated with a VSAM data set, the option is ignored.
You can only specify VS-format records for data sets with consecutive organization.
The record format options for stream-oriented data transmission are discussed in Using stream-oriented data transmission.
The RECSIZE option specifies the record length.
>>-RECSIZE--(--record-length--)--------------------------------><
For files associated with VSAM data sets, record-length is the sum of:
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 you include the RECSIZE option in the file declaration for checking purposes, you should specify the maximum record size. If you specify RECSIZE and it conflicts with the values defined for the data set, the UNDEFINEDFILE condition is raised.
You can specify record-length as an integer or as a variable with attributes FIXED BINARY(31,0) STATIC.
The value is subject to the following conventions:
V-format, and VS- and VBS-format with UPDATE files: 32756
VS- and VBS-format with INPUT and OUTPUT files: 16777215
ASCII data sets: 9999
VSAM data sets: 32761
Note: For VS- and VBS-format records longer than 32,756 bytes, you must specify the length in the RECSIZE option of ENVIRONMENT, and for the DCB subparameter of the DD statement you must specify LRECL=X. If RECSIZE exceeds the allowed maximum for INPUT or OUTPUT, either a record condition occurs or the record is truncated.
If neither of these provides a value, default action is taken (see Record format, BLKSIZE, and RECSIZE defaults).
The BLKSIZE option specifies the maximum block size on the data set.
>>-BLKSIZE--(--block-size--)-----------------------------------><
block-size is the sum of:
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 unspanned. When specifying a blocksize for spanned records, note 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.
block-size can be specified as an integer, or as a variable with attributes FIXED BINARY(31,0) STATIC.
The value is subject to the following conventions:
The relationship of block size to record length depends on the record format:
Notes:
If you do not specify either the record format, block size, or record length for a non-VSAM data set, the following default action is taken:
If neither is specified, the UNDEFINEDFILE condition is raised, except for files associated with dummy data sets, in which case BLKSIZE 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, RECSIZE is set to 120.
If you are using z/OS with the Data Facility Product system-determined block size, DFP determines the optimum block size for the device type assigned. If you specify BLKSIZE(0) in either the DD assignment or the ENVIRONMENT statement, DFP calculates BLKSIZE using the record length, record format, and device type.
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.
>>-GENKEY------------------------------------------------------><
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. You identify the class by including 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 you can retrieve the first record having a key in a particular class by using a READ with the KEY option, you cannot obtain the actual key 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 (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 when the end of a key class is reached. It is your responsibility to check each key if you do not wish to read beyond the key class. Any subsequent execution of the first READ statement would reposition the file to the first record of the key class “ABC”.
If the data set contains no records with keys in the specified class, or if all the records with keys in the specified class are dummy records, the KEY condition is raised. The data set is then positioned either at the next record that has a higher key or at the end of the file.
The presence or absence of the GENKEY option affects the execution of a READ statement which supplies a source key that is shorter than the key length specified in the KEYLEN subparameter. This KEYLEN subparameter is found in the DD statement that defines the indexed data set. If you specify the GENKEY option, it causes the source key to be interpreted as a generic key, and the data set is positioned to the first nondummy record in the data set whose key begins with the source key. If you do not specify the GENKEY option, a READ statement's short source key is padded on the right with blanks to the specified key length, and the data set is positioned to the record that has this padded key (if such a record exists). For a WRITE statement, a short source key is always padded with blanks.
Use of the GENKEY option does not affect the result of supplying a source key whose length is greater than or equal to the specified key length. The source key, truncated on the right if necessary, identifies a specific record (whose key can be considered to be the only member of its class).
You use the SCALARVARYING option in the input/output of varying-length strings; you can use it with records of any format.
>>-SCALARVARYING-----------------------------------------------><
When storage is allocated for a varying-length string, the compiler includes a 2-byte prefix that specifies the current length of the string. For an element varying-length string, this prefix is included on output, or recognized on input, only if SCALARVARYING is specified for the file.
When you use locate mode statements (LOCATE and READ SET) to create and read a data set with element varying-length strings, you must specify SCALARVARYING to indicate that a length prefix is present, since the pointer that locates the buffer is always assumed to point to the start of the length prefix.
When you specify SCALARVARYING and element varying-length strings are transmitted, you must allow two bytes in the record length to include the length prefix.
A data set created using SCALARVARYING should be accessed only by a file that also specifies SCALARVARYING.
You must not specify SCALARVARYING and CTLASA/CTL360 for the same file, as this causes the first data byte to be ambiguous.
Use the KEYLENGTH option to specify the length of the recorded key for KEYED files where n is the length. You can specify KEYLENGTH for INDEXED files.
>>-KEYLENGTH--(--n--)------------------------------------------><
If you include the KEYLENGTH option in a VSAM file declaration for checking purposes, and the key length you specify in the option conflicts with the value defined for the data set, the UNDEFINEDFILE condition is raised.
The ORGANIZATION option specifies the organization of the data set associated with the PL/I file.
.-CONSECUTIVE-. >>-ORGANIZATION--(--+-INDEXED-----+--)------------------------->< '-RELATIVE----'
Data sets with the RECORD attribute are processed by record-oriented data transmission in which data is transmitted to and from auxiliary storage exactly as it appears in the program variables; no data conversion takes place. A record in a data set corresponds to a variable in the program.
Table 14 shows the facilities that are available with the various types of data sets that can be used with PL/I Record I/O.
|
|
VSAM KSDS |
VSAM ESDS |
VSAM RRDS |
INDEXED |
CONSECUTIVE |
REGIONAL (1) |
|---|---|---|---|---|---|---|
|
SEQUENCE |
Key order |
Entry order |
Num- bered |
Key order |
Entry order |
By region |
|
DEVICES |
DASD |
DASD |
DASD |
DASD |
DASD, card, etc. |
DASD |
|
123 |
123 |
123 |
12 |
2 3 tape only |
12 |
|
Alternate index access as above |
123 |
123 |
No |
No |
No |
No |
|
How extended |
With new keys |
At end |
In empty slots |
With new keys |
At end |
In empty slots |
|
Yes, 1 |
No |
Yes, 1 |
Yes, 2 |
No |
Yes, 1 |
The following chapters describe how to use Record I/O data sets for different types of data sets:
There are a number of environment variables that can be set and exported for use with z/OS UNIX.
To set the environment variables system wide so all users have access to them, add the lines suggested in the subsections to the file /etc/profile. To set them for a specific user only, add them to the file .profile in the user's home directory. The variables are set the next time the user logs on.
The following example illustrates how to set environment variables:
LANG=ja_JP NLSPATH=/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/prime/%N LIBPATH=/home/joe/usr/lib:/home/joe/mylib:/usr/lib export LANG NLSPATH LIBPATH
Rather than using the last statement in the previous example, you could have added export to each of the preceding lines (export LANG=ja_JP...).
You can use the ECHO command to determine the current setting of an environment variable. To define the value of BYPASS, you can use either of the following two examples:
echo $LANG echo $LIBPATH
SYSIN is read from stdin and SYSPRINT is directed to stdout by default. If you want either to be associated differently, you must use the TITLE option of the OPEN statement, or establish a DD_DDNAME environment variable naming a data set or another device. Environment variables are discussed above in Setting environment variables.
You can also redirect standard input, standard output, and standard error devices to a file. You could use redirection in the following program:
Hello2: proc options(main);
put list('Hello!');
end;
After compiling and linking the program, you could invoke it from the command line by entering:
hello2 > hello2.out
If you want to combine stdout and stderr in a single file, enter the following command:
hello2 > hello2.out 2>&1
As is true with display statements, the greater than sign redirects the output to the file that is specified after it, in this case hello2.out. This means that the word 'Hello' is written in the file hello2.out. Note also that the output includes printer control characters since the PRINT attribute is applied to SYSPRINT by default.
READ statements can access data from stdin; however, the record into which the data is to be put must have an LRECL equal to 1.