Defining IAM Files in JCL
JCL Allocation
IAM data sets can be defined in JCL, just LIKE VSAM data sets. DFSMS must be active within the system to use this facility; however, the data set does not have to be DFSMS managed. Similar to VSAM, only a subset of the attributes can be specified in JCL. Use of a DATACLAS is encouraged, because that will pick up the free space and share option values, which cannot be specified in JCL. Also, because the JCL defines are actually done under the initiator TCB,IAM does not have access to any IAM Overrides that may be included in the JCL for the define process. The overrides can be specified on the job step that loads the data set, which may or may not be the step that allocates the IAM data set. Because there is no mechanism to pass an OWNER parameter, the data set must either have the literal '$IAM' within the data set name, or be a DFSMS managed data set with '$IAM' in either the STORCLAS or DATACLAS name.
IAM files can also be allocated as temporary data sets, with the same restrictions as temporary VSAM data sets. The dataset will not be cataloged, and it is restricted to a single volume.
To use the IAM JCL define capability, IAM must be in link list. Because the definition is running under the initiator TCB, there is no access to the STEPLIB or JOBLIB to do the allocation. If you have multiple levels of the IAM active, then the level in the link list will perform the define request.
JCL Keywords for IAM Data Set Definition
The following is a table, with a brief description of the JCL DD card keywords that are used when allocating an IAM data set through JCL.
JCL DD card keywords
Keyword | Description |
|---|---|
DATACLAS= | Specifies the name of the DFSMS Data Class being requested for this data set. The file attributes will be obtained from this class. For DFSMS managed data sets, if the name includes the literal $IAM, the dataset will be an IAM data set. |
DSN= | Specifies the 1 to 44 character data set name. For IAM data sets that are not DFSMS managed, the literal $IAM must be part of the dataset name. Temporary datasets begin with a single or double &. |
DISP= | Specifies the disposition of the data set. All VSAM and IAM data sets, except temporary datasets, must be cataloged, and will be cataloged during step initiation when the dataset is allocated. Valid values include: (NEW,CATLG) for permanent data sets, or (NEW,PASS) for temporary data sets. |
DSKEYLBL= | IAM does not support defining a new IAM data set with a Key Label using JCL DD statements. Therefore, do not use the DSKEYLBL keyword; instead run a PGM=IDCAMS job step with a DEFINE CLUSTER statement with a KEYLABEL keyword. |
EATTR= | Specifies whether or not this data set can reside on an EAV volume. Values include: NO – Cannot reside on EAV OPT – Can reside on an EAV |
KEYLEN= | For KSDS type of files, specifies the length of the key. This will override any value determined from a DATACLAS or MODEL if specified. For IAM, valid values are 1 to 249. |
KEYOFF= | For KSDS type of files, specifies the offset of the key within the record (RKP). For IAM files, this must be less than or equal to 4091. |
LIKE | Specifies the name of an existing IAM or VSAM data set from which the RECORG, KEYLEN, KEYOFF, LRECL, and space attributes will be obtained. |
LRECL= | Specifies the maximum record length. For KSDS type of files, this must be at least the value of KEYLEN + KEYOFF. |
MGMTCLAS= | Specifies the DFSMS Management Class that is being requested for this data set. |
RECORG= | Indicates the type of data set to define. Valid values for IAM are KS for a KSDS, ES for an ESDS or RR for an RRDS. IAM does not support the LS type of VSAM data sets. |
STORCLAS= | Specifies the DFSMS Storage Class that is being requested for the data set. |
UNIT= | Specifies the type of device to which the data set is being allocated. |
VOL=SER= | Specifies the volumes to which the data set is being allocated. Note that temporary data sets are limited to one volume. This is not required for DFSMS managed data sets. |
Examples of Defining IAM Data Sets with JCL
The following are some examples of how to define IAM files through JCL. For clarity in the examples, the program being executed is IEFBR14. However, any program could be executed, including programs that may load and access the data set.
Example H: Basic JCL Define of an IAM file
The example below is a basic example of defining an IAM KSDS type of file through JCL. The data set eligibility for an SMS managed volume will be determined by the installations ACS routines.
Basic JCL Define of an IAM File (EX1020H)
//NEWIAMFL DD DSN=new.my$IAM.file,DISP=(NEW,CATLG),
// RECORG=KS,KEYLEN=8,KEYOFF=0,LRECL=128,
// UNIT=SYSDA,VOL=SER=MYVOL1,
// SPACE=(CYL,(20,2))
Example I: Define of an IAM Data set with SMS Classes
In the following example, the file attributes are picked up from the DATACLAS, as well as the request to make the file an IAM file.
JCL Define of an SMS Managed IAMData Set (EX1020I)
//NEWIAMFL DD DSN=new.myfile.cluster,DISP=(,CATLG),
// DATACLAS=(MY$IAMF1),STORCLAS=(PERMVSAM)
Example J: Define of a Temporary IAM Data Set
The example below allocates a temporary IAM data set, whose attributes are being taken from an existing IAM or VSAM data set.
JCL Define of Temporary IAM Data Set (EX1020J)
//TEMPFILE DD DSN=&&TEMP.$IAMFIL,DISP=(,PASS),
// LIKE=my.indexed.cluster,
// UNIT=SYSDA
Example K: Define of an IAM ESDS Data Set
In the following example, an IAM ESDS type of file is being defined.
JCL Example Define of an IAM ESDS File (EX1020K)
//ESDSFILE DD DSN=my.esds$IAM.cluster,DISP=(,CATLG),
// RECORG=ES,LRECL=1020,
// UNIT=SYSDA,VOL=SER=MYVOL1,SPACE=(CYL,(2,1))