Defining an IAM Alternate Index

This is a required parameter. The entry name specified for the alternate index will be the name of the IAM data set. The data and index component names are ignored.

Required parameter that specifies the name of the base cluster that this data set will be an alternate index to. To have an IAM Alternate Index, the base cluster must be an IAM Enhanced Format KSDS or ESDS type of file.

Required parameter that specifies the length of the alternate key, and the relative position of the alternate key within the base cluster. For IAM, the maximum length of the alternate key is 249. Note that each record in the base cluster must be long enough to contain the alternate key.

The IDCAMS default values are: 64,0.

Specifies the average and maximum lengths of the records in the alternate index data set. The minimum record length is 5, plus the alternate key length, plus the length of the key for the base cluster.

Spanned records will be automatically indicated when the maximum record size exceeds the control interval size or when the record size exceeds the size that can fit in a half track block size. The maximum record size for an IAM file is approximately 8 megabytes. The VSAM architecture allows for up to 32,767 non-unique keys per each alternate key, which IAM abides by to insure full VSAM compatibility.

IDCAMS default values are: average=4086 maximum=32600.

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 the BLDINDEX or reorganizations. The secondary quantity will also be used to acquire additional space as needed to handle updates and inserts after the BLDINDEX.

IAM data sets that are not SMS Extended format and are not Large Format are limited to 16 extents per volume. 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 for basic format data sets. To use more than 64k tracks per volume, use either the Large Format data sets, or SMS Extended Format data sets.

Specifies the volumes on which IAM is to allocate the data set. A maximum of 59 volumes can be specified for an IAMdata set, due to z/OS TIOT entry size limitations.

Specifies the maximum amount of virtual storage 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. IAM will refer to this value when calculating the block size it is going to use for the data set, generally increasing the value to one that will maximize utilization on the device type to which the data set is allocated. IAM does store the specified CI SIZE, so that it is an available information if the data set is converted back to VSAM.

Optional keyword that specifies a DDNAME that allocates the volumes on which the IAM file is to be allocated. This keyword can also be used to relate a particular IAM CREATE Override statement with a matching DDN= specification.

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. Unless a file is never updated and never has records added to it, some CI free space should be specified. This is of particular importance to data compressed files that are updated, because even if the application does not change the length, the stored record may end up being longer after compression. For most data sets, CI free space should be kept very small, with 0 being generally recommended, otherwise a lot of DASD space can get wasted with capacity that is not going to be used. CA%: Controls how much DASD space is released at the end of a file load. Using ½ 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 acquire 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 that the attributes of the data set being defined are to be copied from an existing VSAM or IAM alternate index. 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, etc. If you are trying to define a VSAM AIX using an IAM AIX as a model, you MUST provide an OWNER parameter, with a value that does not contain $IAM.

Optional keyword that indicates that the alternate index is to be an IAM data set. IAM will automatically assume that an alternate index is to be an IAM data set when the base cluster is also an IAM data set. If no value has been specified for OWNER, IAM will set it to $IAM in the catalog entry.

Is an optional keyword for existing IAM data sets to re-establish the catalog entry, and update the internal alternate index relationship information. It requires the user to specify the data set name, the volumes on which the data set resides or ANYVOL, and the name of the related base cluster. Recatalog is also used after renaming one or more components of an alternate index sphere, to reset the associated data set names to the new names.

Specifies whether the file being defined can be reloaded (or reorganized) without being redefined. IAM defaults to REUSE, which means, 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. While quite rare, there are a few application programs that rely on the 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). The second parameter specifies how a file is shared between systems.

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 unless files are processed with IAM/RLS or IAM/PLEX. They may not be able to access inserted or updated records, if such records were to be 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. Use of this share option for IAM files is strongly discouraged unless the file is shared using 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.

• 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. Use of this share option for IAM files is strongly discouraged unless the file is shared using IAM/RLS, IAM/PLEX, or some other VSAM sharing software. Due to the nature and structure of the index to the IAMoverflow area, the data integrity of IAM files is compromised by use of this share option value.

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 data set, and in the catalog entry. The keyword PURGE must be specified on the DELETE to cause the file to be scratched.

TO(date) - gives 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) - gives 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: Data set is not date protected.

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

However, the user should be aware that specification of this keyword results in IDCAMS allocating the specified volumes prior to issuing the actual define request. For this reason, it is recommended that this parameter not be specified for IAM files.

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

Specifies whether IAM will upgrade (update) the alternate index as the base cluster is modified.

UPGRADE indicates that IAM will automatically update the alternate index whenever records are updated, inserted, or deleted from the base cluster.

NOUPGRADE indicates that IAM will not automatically update the alternate index.

Default is UPGRADE.