Defining IAM data sets using IDCAMS

Identifies that a VSAM type data set is to be created. This is a required parameter for an IAM data set.

This is a required parameter for an IAM data set. The entry name specified for the cluster will be the name of the IAM data set. The data and index component names are ignored. If '$IAM' appears anywhere in the name the dataset will be created as an IAM data set.

If OWNER($IAM) is coded on the CLUSTER statement, the file will be created as an IAM data set. When '$IAM' is not present in the cluster name, and the $IAM parameter is not otherwise specified, the file will be created as a VSAM cluster.

Required information that indicates the amount of DASD space to be allocated for the IAM data set. The unit of allocation is based on the keyword specified. The first value provided indicates the amount of space to be allocated during the file definition process. For IAM files, the primary quantity must be available on the first volume, otherwise the request will fail. The second value, which is optional, indicates the amount of additional DASD space to request in case the primary quantity is insufficient. The secondary quantity will be used to acquire additional extents during file loads or reorganizations. The secondary quantity will also be used to acquire additional space for Enhanced format IAM data sets as needed to handle record updates and inserts after the file load. This parameter may be omitted if it is specified on a DFSMS Data Class that will be used for this data set.

If the IAM data set being defined is a basic non-VSAM data set it is limited to 16 extents per volume and if Compatible format to a total maximum of 255 extents. The maximum extent size is 64K-1 tracks (65,535), or 4,369 cylinders per volume, which is also the maximum amount of space that can be used by IAM on any single volume. These limits do not apply to Large Format data sets or SMS Extended Format data sets.

Specifies the volumes on which IAM is to allocate the data set. Due to the TIOT limitation, IAM files can reside on a maximum of 59 volumes. The volumes provided can be specific volumes, DFSMS non-specific volume of *, or non-DFSMS non-specific volume of ANYVOL. This parameter can be omitted for DFSMS managed data sets.

For KSDS files, required parameter that specifies the length of the key, and the relative position of the key within the record. The maximum key length supported by IAM is 249. For spanned files the maximum key offset is 4091. Because IAM does not data compress the bytes preceding the key, it is beneficial to place the key as close to an offset of 0 as possible.

The IDCAMS default values are: 64,0.

The first value specifies the average record length in bytes. The second value is the maximum record length. The maximum record size supported by IAM Enhanced Format files is almost 8 megabytes. There is not a specific maximum record size supported by IAM, as the maximum size possible is dependent on several factors, including the block size being used for the file, the key length, and the key offset. The DEFINE request will fail if IAM calculates that it cannot support the specified maximum record size. Files with large record sizes, that exceed the half-track block size on the type of device the file is being defined on, will automatically be defined with the SPANNED attribute based on the IAM Global Option AUTOSPAN.

The average record length is primarily used when the define request specifies that the space is to be allocated by RECORDS. Then IAM (and VSAM) will use the average record length when converting the space value to a device specific quantity. For RRDS (numbered) data sets, if the average record length is equal to the maximum, then a fixed length record RRDS will be defined.

IDCAMS default values are: average=4089 maximum=4089

Specifies the maximum amount of virtual storage in bytes to be used for buffers for this data set. IAM will use this value to calculate the effective MAXBUFNO for accessing the data set, providing it does not go below the default value from the IAM Global Options Table.

For VSAM, this controls the logical and physical block size on DASD for the file. VSAM restricts the size to multiples of 512 or 2048 that usually results in under utilized disk space. IAM takes the size specified and based on the device type being allocated to and the record size, calculates a larger block size for the data set that is a proportion of the track capacity. If the block size developed would result in more blocks per track than the default block factor, which is shipped as 4 blocks on a track, IAM will increase the block size until only that many blocks will fit on a track. The block size may be further adjusted if the block cannot contain at least 4 maximum size records. The default block factor can be changed through the use of IAMZAPOP, by setting the VSAMBLOCKF parameter. The block factor or size can also be set by the B= operand of the IAM CREATE Override.

For IAMESDS files, IAM will use the specified CI SIZE in the calculations for the RBA of each record. When reorganizing an IAM ESDS, users should be careful not to change the CI SIZE, because it can result in different RBA values for the records. This may cause problems for applications that have an index into the ESDS file by RBA.

IAM does store the specified CI SIZE, so that it is available information if the data set is converted back to VSAM.

EXAMPLE OF BLOCK SIZE ON A 3390:

CISZ(4096) IAM's BLKSIZE will be 13682 - 4 blocks per track

CISZ(20480) IAM's BLKSIZE will be 27998 - 2 blocks per track

For DFSMS installations, this parameter specifies the name of the SMS DATA CLASS construct, which provides the allocation attributes for the new data set. The DATACLAS name must have been previously established by the Storage Administrator. Attributes from the DATACLAS will be used, unless otherwise explicitly specified on the DEFINE statement. If the DATACLAS name contains the literal $IAM, and the data set is SMS managed, then the dataset will be defined as an IAM data set.

Values provided by a Data Class include type of data set, ESDS, KSDS, or RRDS, maximum record size, key length and key offset, space allocation values, free space, share options, CI size, and volume count.

Specifies whether or not the data set can reside on an EAV volume which is one that has > 64K cylinders. Specifying OPT indicate the data set can reside on an EAV volume. Specifying NO indicates it cannot reside on an EAV volume.

The default for IAM files is NO, unless the Global Option ENABLE=EAV is set in which case the default is OPT.

Optional keyword that specifies a DD name that allocates the volumes on which the IAM file is to be allocated.

For IAM files, the primary use of this parameter is to provide a mechanism for relating IAM overrides when they are specified on a DDNAME level, with the specific file being defined. For example, if you specify anIAM CREATE Override with a DDNAME=FILE1, then to relate those overrides to the desired file, specify FILE(FILE1) on the DEFINE CLUSTER command. With IAM, there is no need for there to actually be a DD card in the step defining the file with that DDNAME. An alternative to using the file parameter is to code the CREATE override specifying the DSN= (data set name) parameter.

If you are defining only one file in a particular job step, or want the same override for all of the files being defined, on the IAM Create Override statement specify DD=&ALLDD, and do not provide any FILE parameter on the define.

For KSDS type of files or variable length record RRDS files, specifies the amount of space to be reserved for future inserts or updates when the file is being loaded.

CI%—Specifies the amount, as a percentage, of space to be left available in each prime block of the IAM file. This is identical to the VSAM CI free space concept. Low values of no more than 5 are recommended for data compressed files that are subject to update processing. For most other files, 0 is generally the best choice. The concept of free space within a CI or data block works best to handle files with insert activity that are uniformly done across the entire key range of the file, which occurs quite infrequently. Larger values of 20% or higher are generally discouraged as they end up wasting a lot of space resulting in increasing file size and physical I/O.

CA%—For Enhanced format IAM data sets, this controls how much DASD space is released at the end of a file load. Using 1/2 of the specified percentage, a target amount of DASD space to be reserved for future expansion is computed. If the amount of available DASD space within the file extents is equal to or less than the amount to be reserved, then no space is released. IAM will not go after additional extents to meet the space reservation. If the amount of DASD space exceeds the reserved value, then the excess will be released.

If your installation has the DSORG=DA set, then be aware that z/OS will not allow any space to be released.

Specifies the type of journal records that are to be written to the log stream specified by the LOGSTREAMID parameter. The journal records will be written by CICS when the file is processed under CICS, otherwise they will be written by IAM, either directly or via the IAMLOGVR address space. The records written by IAM use the same format as the replication records, and can be used for recoveries by the IAM provided IAMRREST utility. The IAM file must be SMS managed to have this parameter recognized.

ALL—Specifies that both UNDO and REDO journal records are produced.

UNDO—Specifies that UNDO journal records are written that are the contents of records prior to being updated. These records enable updates to be removed by recovery processing.

REDO—Specifies that REDO journal records are written, which are records containing the actual updated record content. These records enable updates to be reapplied to the data set if it was restored for some reason.

NONE—Specifies that no journal records will be written to the file. One might specify this value to indicate subsequent use by IAM logging enabled through the IAM ACCESS Override for selected batch job steps.

Default is that no records will be written to the log stream, unless FRLOG so indicates or LOGREPLICATE is specified. If LOGREPLICATE is specified it supersedes the FRLOG value, and will include ALL types of FRLOG records being produced.

Specifies that a LINEAR type of CLUSTER is being defined. IAM does not support this type of VSAM data set. Specification of LINEAR for an IAM data set will result in the DEFINE failing.

For IAM files that are DFSMS managed, this specifies the recoverability of a data set, and the journaling that IAM will perform. Specification of this parameter will have a different impact on IAM than with VSAM, because IAM provides journaling capabilities that VSAM does not. (Alternatively, journaling options can be specified on the IAM CREATE override JRNAD=). Specifying NONE indicates that the file is not recoverable and IAM will not perform any journaling. Specifying UNDO indicates that the file is recoverable, and IAM will journal the information necessary for backing out updates. Specifying ALL indicates that the file is recoverable and IAM will journal the information necessary for either a backout recovery, or a forward recovery. Refer to the IAM-Journal-and-Recovery, for additional information on IAM journal and recovery services.

When LOGREPLICATE is specified that indicates that data replication journal records are to be written to the system logger log stream identified by the LOGSTREAMID() parameter which is required when LOGREPLICATE is specified. CICS will create the journal records for data sets updated under it’s control, and IAM will create the journal records, either directly or via the IAMLOGVR address space, when updates are done outside CICS. The journal records written are those required for the GDPS Active-Active solution and the IIDR for VSAM data replication product from IBM. The IAM program IAMRREST can use these records when it is performing a recovery process on an IAM data set. If specified, it will replace the type of logging done by IAM based on the LOG() parameter and the IAM JRNAD override parameter.

NOLOGREPLICATE which is the default value indicates that no replication records will be created for this data set.

Specifies the name of the system logger recovery log for the IAM data set. This parameter is required when either FRLOG() or LOGREPLICATE has been specified. The required journal records will be written to the log stream by CICS for applications running under CICS, and by IAM, either directly or via the IAMLOGVR address space, for applications not running under CICS.

Specifies that the attributes of the data set being defined will be copied from an existing VSAM or IAM data set. This capability is only relevant for basic file characteristics, such as record size, key length and offset, space allocation values, volumes, and free space values. Any IAM Overrides are not picked up by the MODEL parameter. Likewise, any VSAM file attributes that are ignored by IAM are not available either, such as IMBED, SPEED, REPLICATE, KEYRANGES, and so on.

If you are trying to define a VSAM file using anIAM file as a model, you must provide an OWNER parameter, with a value that does not contain $IAM.

Is an optional keyword for existing IAM data sets to reestablish the catalog entry. Requires the user to specify the data set name, the volumes, and OWNER($IAM) if $IAM is not in the data set name. Recatalog is used after renaming one or more components of an alternate index sphere, to reset the dataset relation names to the new names.

RECATALOG can also be used to perform an ALTER type of function for IAM files with changing various defined values for an existing data set from the CREATE override statement. Values that can be changed include: BUFSPACE, FRLOG, JRNAD, LOGREPLICATE, LOGSTREAM, MINBUFNO, MAXBUFNO, RLSID, and SHAREOPTION.

Specifies whether the file being defined can be reloaded (or reorganized) without being redefined. IAM defaults to REUSE, which means that, any IAM file can be reloaded without having to be deleted and redefined. To use this feature with IDCAMS REPRO, specify the REUSE keyword.

IAM does provide a Global Option, ENABLE=NOREUSE, which if set will cause IAM to honor the specification of REUSE or NOREUSE. If that Global Option has been set, then IAM will honor the NOREUSE setting just like VSAM. A few applications are dependent on NOREUSE setting.

NOREUSE will not allow a file to be reloaded without being deleted and redefined. An exception to this is made if the program issuing the OPEN is FDRREORG, in which case it will be allowed. If any other attempt is made to do so, the OPEN will fail with a return code of 8, and the ACB error flag set to 232, or x'E8'.

Specifies the level of protection provided by the access method to prevent or allow sharing of data within the file. The protection mechanisms include the z/OS ENQ service, and the internal IAM buffering techniques.

The first parameter specifies how a file can be shared in the same system (CPU/LPAR). The second parameter specifies how a file is shared between systems or LPARs.

Cross Region Share Option Values:

• Any number of users for read OR one user for update. The file's structure, data integrity, and read integrity are fully preserved.
• Any number of users for read AND one user for update. The file's structure and data integrity are fully preserved. If the file is currently opened for update, other users reading the file do not have read integrity. They may not be able to access records that were moved or added to the overflow areas of the file, without closing and reopening the data set.
• Any number of users for read or update and users are responsible for integrity. Updated blocks are immediately written back out to DASD.

• Any number of users for read or update, and users are responsible for integrity. IAM will use only a single buffer, and each logical I/O request will cause the buffer to be refreshed, and subsequently rewritten if the record is updated. 

  Warning

  Use of this share option for IAM files is strongly discouraged, unless you share the data set with IAM/RLS, IAM/PLEX, or some other VSAM sharing software. Due to the nature and structure of the index to the IAM overflow area, the data integrity of IAM files is compromised by use of this share option value.

IAM supports SPANNED records on Enhanced Format files, with a maximum record size of almost 8 megabytes. The spanned attribute is also automatically assigned when the maximum record size exceeds the maximum half track block size to make more efficient use of space.

For DFSMS installations, this parameter specifies the name of the DFSMS Storage Class construct. For datasets that are to be placed on DFSMS volumes, Storage Class must be either implicitly specified by the ACS routines, or explicitly specified on the DEFINE command. If the Storage Class Name contains the literal $IAM, the file will be defined as an IAM file.

IAM files are always allocated as if they were unique clusters. However, it may be necessary to specify this parameter when using the IAM non-specific allocation (ANYVOL) and the MODEL parameter. SUBALLOCATION will prevent IDCAMS from allocating the volumes indicated in the VOLUME parameter when the MODEL parameter is specified.

Specifies the retention period for the file being defined. This parameter has the same meaning for an IAM file as a VSAM file. The expiration date is placed in the VTOC for the dataset, and in the catalog entry. The keyword PURGE must be specified on the DELETE to cause the file to be scratched.

• TO(date)—Indicates the date in the form YYYYDDD (four or two digit year and three digit Julian date), through which the IAM file defined is to be date protected.
• FOR(days)—indicates the number of days up to 9998, through which the IAM file being defined is to be date protected. A value of 9999 results in permanent retention.
• Default—Dataset is not date protected.

This parameter has no relevance for IAM files, as IAM files are always unique.

If the customer is using the IAM non-specific device allocation, that is ANYVOL, then this parameter must not be specified.