Rational Developer for System z
Enterprise PL/I for z/OS, Version 3.8, Programming Guide

Specifying characteristics in the ENVIRONMENT attribute

You can use various options in the ENVIRONMENT attribute. Each type of file has different attributes and environment options, which are listed below.

The ENVIRONMENT attribute

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.

Read syntax diagramSkip visual syntax diagram>>-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.

Table 13. Attributes of PL/I file declarations
Data set type
S
t
r
e
a
m
Record
Legend:
C
Checked for VSAM
D
Default
I
Must be specified or implied
N
Ignored for VSAM
O
Optional
S
Must be specified
-
Invalid
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
F|FB|FS|FBS|V|
  VB|VS|VBS||U
I
 
S
 
S
 
-
 
-
 
-
 
N
 
-
 
-
 
N
 
VS and VBS are invalid
 with Stream
F|FB|U
S
S
-
-
-
-
N
-
-
N
ASCII data sets only
F|V|U
-
-
-
S
-
-
N
S
-
N
Only F for REGIONAL(1)
F|FB|V|VB
-
-
-
-
-
S
N
-
S
N
 
RECSIZE(n)
I
I
I
I
S
I
C
I
I
C
RECSIZE and/or BLKSIZE must
 be specified for consecutive
BLKSIZE(n)
I
I
I
I
-
I
N
I
I
N
 indexed, and regional files
SCALARVARYING
-
O
O
O
-
O
O
O
O
O
Invalid for ASCII data sets
CONSECUTIVE
D
D
D
-
-
-
O
-
-
O
Allowed for VSAM ESDS
LEAVE|REREAD
O
O
O
-
-
-
-
-
-
-

CTLASA|CTL360
-
O
O
-
-
-
-
-
-
-
Invalid for ASCII data sets
GRAPHIC
O
-
-
-
-
-
-
-
-
-
 
INDEXED
-
-
-
-
-
S
O
-
S
O
Allowed for VSAM ESDS
KEYLOC(n)
-
-
-
-
-
O
-
-
O
-
 
ORGANIZATION
D
-
-
-
-
-
-
-
-
-
 
GENKEY
-
-
-
-
-
O
O
-
O
O
INPUT or UPDATE files only;
 KEYED is required
REGIONAL(1)
-
-
-
S
-
-
-
S
-
-
 
VSAM
-
-
-
-
-
-
S
-
-
S
 
BKWD
-
-
-
-
-
-
O
-
-
O
 
REUSE

 
-

 
-

 
-

 
-

 
-

 
-

 
O

 
-

 
-

 
O

 
OUTPUT file only

 
Notes:
  1. A file with the INPUT attribute cannot have the PRINT attribute.
  2. Keyed is required for INDEXED and REGIONAL output.
Data set organization options

The options that specify data set organization are:

Read syntax diagramSkip visual syntax diagram>>-+-CONSECUTIVE-------+---------------------------------------><
   +-INDEXED-----------+
   +-REGIONAL--(--1--)-+
   '-VSAM--------------'
 

Each option is described in the discussion of the data set organization to which it applies.

Other ENVIRONMENT options

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:

ENVIRONMENT option
DCB subparameter
Record format
RECFM1
RECSIZE
LRECL
BLKSIZE
BLKSIZE
CTLASA|CTL360
RECFM
KEYLENGTH
KEYLEN

Note:
1VS must be specified as an ENVIRONMENT option, not in the DCB.

Record formats for record-oriented data transmission

Record formats supported depend on the data set organization.

Read syntax diagramSkip visual syntax diagram>>-+-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.

Record formats for stream-oriented data transmission

The record format options for stream-oriented data transmission are discussed in Using stream-oriented data transmission.

RECSIZE option

The RECSIZE option specifies the record length.

Read syntax diagramSkip visual syntax diagram>>-RECSIZE--(--record-length--)--------------------------------><
 

For 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 prefix); fixed-length and undefined-length records do not require any.

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:

Maximum:
Fixed-length, and undefined (except ASCII data sets): 32760

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.

Zero value:
A search for a valid value is made first:

If neither of these provides a value, default action is taken (see Record format, BLKSIZE, and RECSIZE defaults).

Negative Value:
The UNDEFINEDFILE condition is raised.

BLKSIZE option

The BLKSIZE option specifies the maximum block size on the data set.

Read syntax diagramSkip visual syntax diagram>>-BLKSIZE--(--block-size--)-----------------------------------><
 

block-size is the sum of:

  1. The total length(s) of one of the following:

    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.

  2. Any further control bytes required.
  3. Any block prefix bytes required (ASCII data sets only).

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:

Maximum:
32760
Zero value:
If you set BLKSIZE to 0, under z/OS the Data Facility Product sets the block size. For an elaboration of this topic, see Record format, BLKSIZE, and RECSIZE defaults.
Negative value:
The UNDEFINEDFILE condition is raised.

The relationship of block size to 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.

Notes:

Record format, BLKSIZE, and RECSIZE defaults

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:

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

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

Read syntax diagramSkip visual syntax diagram>>-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).

SCALARVARYING option — varying-length strings

You use the SCALARVARYING option in the input/output of varying-length strings; you can use it with records of any format.

Read syntax diagramSkip visual syntax diagram>>-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.

KEYLENGTH option

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.

Read syntax diagramSkip visual syntax diagram>>-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.

ORGANIZATION option

The ORGANIZATION option specifies the organization of the data set associated with the PL/I file.

Read syntax diagramSkip visual syntax diagram                    .-CONSECUTIVE-.
>>-ORGANIZATION--(--+-INDEXED-----+--)-------------------------><
                    '-RELATIVE----'
 

CONSECUTIVE
Specifies that the files is associated with a consecutive data set. A consecutive file can be either a native data set or a VSAM, ESDS, RRDS, or KSDS data set.
RELATIVE
Specifies that the file is associated with a relative data set. RELATIVE specifies that the data set contains records that do not have recorded keys. A relative file is a VSAM direct data set. Relative keys range from 1 to nnnn.

Data set types used by PL/I record I/O

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.

Table 14. A comparison of data set types available to 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
ACCESS
 
1
By key
2
Sequential
3
Backward
 
 
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
DELETION
 
1
Space reusable
2
Space not reusable
 
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:

z/OS UNIX System Services Only

Setting environment variables

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
End of z/OS UNIX System Services Only
z/OS UNIX System Services Only

PL/I standard files (SYSPRINT and SYSIN)

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.

End of z/OS UNIX System Services Only
z/OS UNIX System Services Only

Redirecting standard input, output, and error devices

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.

End of z/OS UNIX System Services Only

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)