Optional Parameters

ACCOUNT(account–info)

Account is supported only for SMS-managed VSAM or non-VSAM data sets.

account–info: Use this to change accounting information and user data for the data set. It must be between 1 and 32 bytes; otherwise, you will receive an error message.

Abbreviation: ACCT

ADDVOLUMES(volser [ volser])

This provides the volumes that are to be added to the list of candidate volumes. You can use ALTER ADDVOLUMES to add candidate volumes to non-managed VSAM data sets and SMS-managed VSAM, non-VSAM, and generation data sets (GDS). Only nonspecific volumes can be added to SMS-managed, non-VSAM data sets and GDS data sets. If an ALTER ADDVOLUMES is done to a data set already opened and allocated, the data set must be closed, unallocated, reallocated, and reopened before VSAM can extend onto the newly added candidate volume. Adding a nonexistent volume to the list can result in an error when the data set is extended. Ensure that the volume exists and is online before attempting to extend the data set.

Restriction: This does not work with non-SMS non-VSAM.

SMS might not use candidate volumes for which you request specific volsers with the ADDVOLUMES parameter. Sometimes a user-specified volser for an SMS-managed data set results in an error. To avoid candidate-volume problems with SMS, you can have SMS choose the volser used for a candidate volume. To do this, you can code an * for each volser that you request with the ADDVOLUMES parameter. If, however, you request both specified and unspecified volsers in the same command, you must enter the specified volsers first in command syntax. The system does not allocate space on candidate volumes until VSAM extends to the candidate volume. This includes SMS-managed data sets with Guaranteed Space.

Abbreviation: AVOL

BUFFERSPACE(size)

Provides the amount of space for buffers. The size you specify for the buffer space helps VSAM determine the size. IBM® recommends that the size you give is equal to or greater than the amount specified in the original definition. If the amount is less, VSAM attempts to get enough space to contain two data component control intervals and, if the data is key-sequenced, one index component control interval. You can specify BUFFERSPACE only for a catalog or for the data component of a cluster or alternate index. If you use BUFFERSPACE for a catalog, then you must specify the CATALOG parameter.

The BUFFERSPACE parameter is ignored for VSAM record-level sharing (RLS) access and DFSMStvs access.

size: Is the amount of space for buffers. This helps VSAM determine the size of the data component's and index component's control interval.
Size can be entered in decimal (n), hexadecimal (X'n'), or binary (B'n') form. The specified size should not be less than the space needed to contain two data component control intervals and, if the data is key-sequenced, to contain one index control interval. If the given size is less than what VSAM requires, it gets it when the data set is opened.
Note: The limitations of the bufferspace value on how many buffers will be allocated is based on storage available in your region, and other parameters or attributes of the data set.

Abbreviations: BUFSP or BUFSPC

BUFND(number)

Gives the number of I/O buffers VSAM is to use for transmitting data between virtual and auxiliary storage. The size of the buffer area is the size of the data component control interval. This parameter only applies the data component of a catalog.

The BUFND parameter is ignored for VSAM RLS access and DFSMStvs access.

number: Is the number of data buffers you can use. The minimum number is 3, and the maximum is 32767.

Abbreviation: BFND

BUFNI(number)

Is the number of I/O buffers VSAM uses for transmitting the contents of index entries between virtual and auxiliary storage for keyed access. The size of the buffer area is the size of the index control intervals. This parameter only applies the index component of a catalog.

When altering BUFNI for a catalog other than the current master on which this command is issued, you will need to include the CATALOG parameter with the name of the catalog whose index you are altering.

The BUFNI parameter is ignored for VSAM RLS and DFSMStvs access.

number: Is the number of index buffers you can use. The minimum number is 2 and the maximum is 32767.

Abbreviation: BFNI

BWO(TYPECICS|TYPEIMS|NO)

Use this parameter if backup-while-open (BWO) is allowed for the VSAM sphere. BWO applies only to SMS data sets and cannot be used with TYPE(LINEAR).

If BWO is specified in the SMS data class, the specified BWO value is used as part of the data set definition, unless BWO was previously defined with an explicitly specified or modeled DEFINE attribute.

TYPECICS

Use TYPECICS to specify BWO in a CICS® environment. For RLS processing, this activates BWO processing for CICS® or DFSMStvs, or both. For non-RLS processing, CICS determines whether to use this specification or the specification in the CICS file control table (FCT).

Exception: If CICS determines that it will use the specification in the CICS FCT, the specification might override the TYPECICS parameter for CICS processing.

Abbreviation: TYPEC

TYPEIMS: If you want to use BWO processing in an Information Management System (IMS™) environment, use the TYPEIMS parameter.
Abbreviation: TYPEI

NO: Use this when BWO does not apply to the cluster.
Exception: If CICS determines that it will use the specification in the CICS FCT, the specification might override the NO parameter for CICS processing.

CATALOG(catname)

Specifies the catalog containing the entry to be altered.

To assign catalog names for SMS-managed data sets, you must have access to the RACF® STGADMIN.IGG.DIRCAT FACILITY class. See Storage Management Subsystem (SMS) Considerations for more information. If you are altering BUFNI for a catalog other than the current master catalog on the system this command is issued on, then this is a required parameter.

catname: Is the name of the catalog that contains the entry.

Abbreviation: CAT

CCSID(value)

Is the Coded Character Set Identifier attribute; it identifies:

Encoding scheme identifier
Character set identifier or identifiers
Code page identifier or identifiers
Additional coding required to uniquely identify the coded graphic used

You can use Coded Character Set Identifier (CCSID) only for system-managed data sets. If the CCSID parameter is not in the catalog at the time ALTER is called, it is created.

The value for CCSID can be specified in decimal (n), hexadecimal (X''), or binary (B''). The acceptable range of values is 0 (X'0'') to 65535 (X'FFFF'').

ECSHARING|NOECSHARING

Indicates whether sharing this catalog can be performed through the coupling facility.

ECSHARING: Enhanced catalog sharing (ECS) is allowed. ECS is a catalog sharing method that makes use of a coupling facility to increase the performance of shared catalog requests. Please read about ECS in z/OS DFSMS Managing Catalogs before enabling ECS for a catalog.
Abbreviation: ECSHR
NOECSHARING: Enhanced catalog sharing (ECS) is not allowed. This is the default. Catalog sharing is performed, but the ECS sharing method is not be used.
Abbreviation: NOECSHR

EMPTY|NOEMPTY

Specifies what is to happen when the maximum number of generation data sets (GDSs) has been cataloged. If the generation data group (GDG) is full (the LIMIT is reached), this attribute determines whether all GDSs or just the oldest GDSs are processed.

For an SMS-managed GDS, if the NOSCRATCH attribute is used, the GDS is uncataloged from its GDG base and is recataloged outside its GDG base as an SMS non-VSAM entry with the rolled-off status.

EMPTY: Specifies that, when the maximum number of GDSs is exceeded, all the GDSs are uncataloged or deleted.
Abbreviation: EMP
NOEMPTY: Used when the maximum number of GDSs is exceeded. This parameter specifies that only the oldest GDS is uncataloged or deleted.
Abbreviation: NEMP

ERASE|NOERASE

Indicates whether to erase the component when its entry in the catalog is deleted.

ERASE: Overwrites the component with binary zeros when its catalog entry is deleted. If the cluster or alternate index is protected by a RACF generic or discrete profile, use RACF commands to assign an ERASE attribute as part of this profile so that the data component is automatically erased upon deletion.
Abbreviation: ERAS
NOERASE: Specifies the component is not to be overwritten with binary zeros when its catalog entry is deleted. NOERASE resets only the indicator in the catalog entry that was created from a prior DEFINE or ALTER command. If the cluster or alternate index is protected by a RACF generic or discrete profile that specifies the ERASE attribute, it is erased upon deletion. Only RACF commands can be used to alter the ERASE attribute in a profile.
Abbreviation: NERAS

EXCEPTIONEXIT(entrypoint)

Is the name of the user-written routine that receives control if an exception (usually an I/O error) occurs while the entry's object is being processed. An exception is any condition that causes a SYNAD exit. The object's exception exit routine is processed first, then the user's SYNAD exit routine receives control.

Abbreviation: EEXT

EXTENDEDADDRESSABLE

The non SMS VSAM LDS will be made eligible for Extended Addressability.

This parameter is only valid for a non SMS VSAM LDS. The Alter will not be allowed if the data set is open at the time of alter. This parameter cannot be NULLIFIED (for example: once a data set is marked for EA it cannot be unmarked).

Abbreviation: EXTADDR

FIFO|LIFO

Specifies the order in which the GDS list is returned for data set allocation when the GDG name is supplied on the DD statement.

FIFO: The order is the oldest GDS defined to the newest GDS.
LIFO: The order is the newest GDS defined to the oldest GDS. This is the default value.

The JCL keyword GDGORDER can be used to override the value specified here to allow individual jobs to select the order of the data.

FILE(ddname)

Specifies one of the following:

The name of a DD statement that describes the volume that contains the data set to be altered.
The name of a DD statement that identifies the volume of an entry that will be renamed. The entry must be a non-VSAM data set or the data or index component of a cluster, alternate index, or page space.
The name of a DD statement that describes a partitioned data set when a member is to be renamed.

If you identify multiple volumes of different device types with FILE, use concatenated DD statements. If you specify ADDVOLUMES or REMOVEVOLUMES, the volume being added or removed must be identified. If FILE is not specified, an attempt is made to dynamically allocate the object's data set. Therefore, the object's volume must be mounted as permanently resident or reserved.

Restriction: While the FILE parameter can preallocate a volume where the data set resides, it does not direct the ALTER request to the data set to be altered. Instead, a catalog search is done to locate the data set to be altered.

FILEDATA(TEXT|BINARY)

Use one of the following:

TEXT: Specifies that the data in the data set is text. If the data set is read or written across the network, the data in this data set is EBCDIC on z/OS® and ASCII on the workstation.
BINARY: Specifies that data is to be processed as is.

FREESPACE(CI-percent[ CA-percent]) Abbreviation: FSPC

Indicates the percent of free space left after any allocation. CI-percent is a percentage of the amount of space to be preserved for adding new records and updating existing records, with an increase in the length of the record. Because a CI is split when it becomes full, the CA might also need to be split when it is filled by CIs created by a CI split. The amounts, as percentages, must be equal to, or less than, 100. If you use 100% of free space, one record is placed in each control interval and one control interval is placed in each control area (CA).

Use this parameter to alter the data component of a cluster, alternate index, or catalog.

If the FREESPACE is altered after the data set has been loaded, and sequential insert processing is used, the allocation of free space is not honored.

FRLOG(NONE|REDO)

Specifies whether VSAM batch logging can be performed for your VSAM data set. VSAM batch logging is available with CICS VSAM Recovery V3R1.

NONE: Disables the VSAM batch logging function for your VSAM data set. Changes made by applications are not written to the MVS™ log stream indicated on the LOGSTREAMID parameter.
REDO: Enables the VSAM batch logging function for your VSAM data set. Changes made by applications are written to the MVS log stream indicated in the LOGSTREAMID parameter. If you specify FRLOG(REDO), you must also specify LOGSTREAMID for that data set, unless the log stream is already defined.

Restrictions:

Use the FRLOG parameter only if you want to enable (REDO) or disable (NONE) VSAM batch logging. Do not use the FRLOG parameter for data sets that are not intended for use with VSAM batch logging.
If FRLOG is specified, these rules apply to the data set:
- Must be SMS-managed
- Cannot be LINEAR or a temporary data set

INHIBIT|UNINHIBIT

Specifies whether the entry being altered can be accessed for any operation or only for read operations.

INHIBIT: Used when the entry being altered is to be read only.
Abbreviation: INH
UNINHIBIT: Indicates that the read-only restriction set by a previous ALTER or EXPORT command is to be removed.
Abbreviation: UNINH

KEYS(length offset)

Specifies the length and offset of the object's key. If the altered entry defines an alternate index, offset applies to the alternate key in the data records in the base cluster.

Restrictions: Use KEYS if all the following are true:

The object whose entry is being altered is an alternate index, a path, a key-sequenced cluster, or a data component of a key-sequenced cluster or alternate index.
The object whose entry is being altered contains no data records.
The values for KEYS in the object's catalog entry are default values. For default values, see the DEFINE command for the object.
The new values for KEYS do not conflict with the control interval size specified when the object was defined.
The key fits within the record whose length is specified by the RECORDSIZE parameter.
The key fits in the first record segment of a spanned record.

length offset: Is the length of the key (between 1 and 255), in bytes, and its displacement from the beginning of the data record, in bytes. The length of the offset cannot be greater than the length of the data record.

If the values for KEYS in the object's catalog entry are not default values and ALTER KEYS specifies those same values, processing continues for any other parameters specified in the command, and no error message is issued.

LOG(NONE|UNDO|ALL)

Establishes whether the sphere to be accessed with VSAM record-level sharing (RLS) or DFSMStvs is recoverable or nonrecoverable. It also indicates whether or not forward recovery logging should be done for the sphere. LOG applies to all components in the VSAM sphere.

NONE: Indicates that neither an external backout nor a forward recovery capability is available for the spheres accessed in VSAM RLS or DFSMStvs mode. If you use this, VSAM RLS and DFSMStvs consider the sphere to be nonrecoverable.
UNDO: Specifies that changes to the sphere accessed in VSAM RLS or DFSMStvs mode can be backed out using an external log. VSAM RLS and DFSMStvs consider the sphere recoverable when you use LOG(UNDO).
ALL: Specifies that changes to the sphere accessed in VSAM RLS or DFSMStvs mode can be backed out and forward recovered using external logs. VSAM RLS and DFSMStvs consider the sphere recoverable when you use LOG(ALL). When you specify LOG(ALL), you must also specify the LOGSTREAMID parameter, unless it is already defined.
VSAM RLS allows concurrent read or update sharing for nonrecoverable spheres through commit (CICS) and non-commit protocol applications. For a recoverable sphere, an application must use DFSMStvs to be able to open the sphere for update using VSAM RLS access.

Restriction: LOG cannot be used with LINEAR.

LOGREPLICATE|NOLOGREPLICATE

Identifies whether or not the VSAM data set being defined is eligible for VSAM replication.

LOGREPLICATE: VSAM data set is eligible for VSAM replication. The update will be captured in the replication log identified by the LOGSTREAMID parameter. When you specify LOGREPLICATE, you must also specify LOGSTREAMID if a value for LOGSTREAMID does not already exist for the data set.
Abbreviation: LOGR
NOLOGREPLICATION: VSAM data set is not eligible for VSAM replication. This is the default value.

Abbreviation: NOLOGR

LOGSTREAMID(logstream)

Changes or adds the name of the forward recovery log stream. It applies to all components in the VSAM sphere.

logstream: Is the name of the forward recovery log stream. This can be a fully qualified name up to 26 characters, including separators. This parameter is required if you have specified LOG(ALL).

Abbreviation: LSID

Restriction: LOGSTREAMID cannot be used with LINEAR.

LIMIT(limit)

Used to modify the maximum number (between 1 and 255, or 999 for an extended GDG) of active generation data sets (GDSs) that might be associated with a generation data group (GDG) base.

limit: If the limit is less than the current number of active generations, the oldest generations are rolled off until the new limit is satisfied. Any GDSs that are rolled off by this command are listed showing their new status (recataloged, uncataloged, or deleted). For more information about limit processing of a GDS, see z/OS DFSMS Managing Catalogs.
If the limit is greater than the current number of active generations, it does not cause the roll-in of existing rolled off GDSs. For this function, see the ROLLIN parameter.

LISTCAT(PREFIX|NOPREFIX)

Specified if the user ID will be added as the first qualifier of the entry name. These keywords apply when IDCAMS LISCAT is invoked by TSO and LISTCAT keyword ENTRY or LEVEL is specified. PREFIX/NOPREFIX are ignored when LISTCAT is running in batch. PREFIX and NOPREFIX are mutually exclusive.

PREFIX: User ID will be added to entry names which are not enclosed in quotes. This is default.
NOPREFIX: User ID will not be added to the entry names. They will be processed as they are specified in the LISTCAT command.

LOCK|UNLOCK

Controls the setting of the catalog lock attribute, and therefore checks access to a catalog. Use LOCK or UNLOCK when the entry name identifies a catalog. If the LOCK|UNLOCK parameter is not specified, the status of the catalog lock attribute is not changed. Before you lock a catalog, review the information on locking catalogs in z/OS DFSMS Managing Catalogs.

LOCK: Is used when the catalog identified by entryname is to be locked. Locking a catalog makes it inaccessible to all users without read authority to RACF FACILITY class profile IGG.CATLOCK (including users sharing the catalog on other systems).
For protected catalogs, locking an unlocked catalog requires ALTER authority for the catalog being locked, and read authority to RACF FACILITY profile IGG.CATLOCK. For unprotected catalogs, locking an unlocked catalog requires read authority to RACF FACILITY class profile IGG.CATLOCK.
UNLOCK: Specifies that the catalog identified by entryname is to be unlocked. For RACF and nonprotected catalogs, unlocking a locked catalog requires read authority to RACF FACILITY class profile IGG.CATLOCK.

MANAGEMENTCLASS(class)

For SMS-managed data sets: Gives the name, 1 to 8 characters, of the management class for a data set. Your storage administrator defines the names of the management classes you can include. If MANAGEMENTCLASS is used for a non-SMS-managed data set, or if SMS is inactive, the ALTER command is unsuccessful.

When the storage or management class is altered for a DFSMShsm migrated data set, ALTER will not recall the data set to make the change, provided no other parameters are specified.

You must have RACF access authority to alter the management class.

Abbreviation: MGMTCLAS

NEWNAME(newname)

Indicates that the entry to be altered is to be given a new name.

When you rename an SMS-managed data set residing on DASD, the MGMTCLAS ACS routine is called and lets you reassign a new management class.

You can use ALTER NEWNAME to rename SMS-managed generation data sets (GDS). Table 1 shows how NEWNAME resolves renaming a GDS under different conditions. You can successfully rename the following:

An SMS-managed GDS to an SMS-managed non-VSAM data set
An SMS-managed non-VSAM data set to an SMS-managed GDS
An SMS-managed GDS to another SMS-managed GDS

Restriction: Catalog names and catalog component names cannot be renamed.

You might not be able to rename a data set if you are changing the high-level qualifiers of the data set's name and those qualifiers are an alias name of a catalog. (The number of high-level qualifiers used to form an alias can be one to four, depending on the multilevel alias search level used at your installation.)

If you are changing a high-level qualifier, NEWNAME acts differently, depending on whether the data set being renamed is SMS-managed or non-SMS-managed, and whether the data set has aliases or not. Table 1 shows how NEWNAME resolves under different conditions.

Table 1. How NEWNAME Resolves When Change of Catalog is Required
Data Set Type	SMS	Non-SMS
VSAM	ALTER unsuccessful—entry not renamed	ALTER successful—entry remains in the source catalog
non-VSAM with no aliases	ALTER successful—entry is recataloged in target catalog.	ALTER successful—entry remains in the source catalog
non-VSAM with aliases	ALTER unsuccessful—entry not renamed	ALTER successful—entry remains in the source catalog
GDS with no aliases	ALTER successful—entry is recataloged in target catalog.	ALTER unsuccessful—entry not renamed
GDS with aliases	ALTER unsuccessful—entry not renamed	ALTER unsuccessful—entry not renamed
Note: The source catalog is the catalog containing the original entry. The target catalog is the catalog in which the new name would normally be cataloged according to a catalog alias search.

Restriction: Do not change the name of a data set for which there are back outs that need to be done. If you change the data set name in this case, it is impossible to back out the changes and the data set is in an inconsistent state, which can cause data integrity problems.

If you want to define a data set into a particular catalog, and that catalog is not the one chosen according to the regular search, then you must have authority to RACF STGADMIN.IGG.DIRCAT facility class. For more information on this facility class see z/OS DFSMSdfp Storage Administration.

To give an altered entry a new name:

Unless the data set being renamed is a path, the data set's volume must be mounted because the volume table of contents (VTOC) is modified.
You can use the FILE parameter to supply a JCL DD statement to allocate the data set. If you do not supply a DD statement, an attempt is made to allocate the data set dynamically. The volume must be mounted as either permanently resident or reserved.

If another program has access to the data set while this is being done, the program might not be able to access the data set after it is renamed. This can result in an error.
If you include generic names, you must define both entryname and newname as generic names.
If you are renaming a member of a non-VSAM partitioned data set, the newname must be specified in the format: pdsname(membername).
If you are renaming a VSAM data set that is RACF protected, the existing RACF data set profile will be renamed.
If you are renaming a tape data set, you must meet two conditions:
- Both the old and new data set names must be greater than 16 characters
- The last 17 characters of the old and new data set names must match
If these conditions are not met, the system will issue message IDC3009I RC48 RSN 74 stating that the ALTER NEWNAME of the tape data set is incorrect.
If you are using ALTER NEWNAME, you must have the following authority:
- ALTER authority for the source data set or for the catalog containing the source data set
- ALTER authority for the target data set or for the catalog containing the target data set, or CREATE authority for the group
If there is a data set profile for the new data set name prior to the ALTER command, the command ends, and the data set name and protection attributes remain unchanged.
If the old profile is not found or cannot be altered to the new name, the NEWNAME action is not completed in the catalog, and an error message indicates why the action is not completed.

If renaming is unsuccessful, it is possible that either the object exists with both the original name and the new name, or that the data set was not closed.

Abbreviation: NEWNM

NULLIFY([AUTHORIZATION(MODULE|STRING)]

[BWO][CODE][EXCEPTIONEXIT]

[LOG][LOGSTREAMID][OWNER]

[RETENTION])

Specifies that the protection attributes identified by subparameters of NULLIFY be nullified. Attributes are nullified before any respecification of attributes is done.

Abbreviation: NULL

AUTHORIZATION(MODULE|STRING)

Is used when the user authorization routine or the user authorization record is to be nullified.

Abbreviation: AUTH

MODULE: Removes the module name from the catalog record, but the module itself is not to be deleted. Both the user authorization routine and the user authorization record (character string) are nullified.
Abbreviation: MDLE
STRING: Nullifies the authorization record, but the corresponding module is not nullified.
Abbreviation: STRG

BWO

Use this parameter to remove the BWO specification from the sphere.

CODE

Nullifies the code name used for prompting.

EXCEPTIONEXIT

Nullifies the entry's exception exit. The module name is removed from the catalog record, but the exception-exit routine itself is not deleted.

Abbreviation: EEXT

LOG

Nullifies the log parameter. NULLIFY(LOG) option is supported for catalogs in the same manner as non catalog VSAM data sets.

VSAM RLS or DFSMStvs access to the sphere is not permitted when the log parameter is nullified.

LOGSTREAMID

When you use this, the name of the forward recovery log stream is nullified. NULLIFY(LOGSTREAMID) is not allowed if the data set has a value of LOG(ALL).

Abbreviation: LSID

MANAGEMENTCLASS

Use this parameter to remove the management class from SMS-managed data set.

Abbreviation: MGMTCLAS

OWNER

Nullifies the owner identification.

RETENTION

Nullifies the retention period that was used in a TO or FOR parameter.

Abbreviation: RETN

OWNER(ownerid)

Specifies the owner identification for the entry being altered.

PURGE|NOPURGE

Specifies whether to override expiration dates when a generation data set (GDS) is rolled off and the SCRATCH parameter is set. PURGE will override the expiration date and cause the VTOC entry to be deleted regardless of the expiration date. PURGE is ignored when NOSCRATCH is specified, either explicitly or as the default. End of change

RECLAIMCA|NORECLAIMCA

Specifies the CA reclaim attribute of a key-sequence data set (KSDS).

RECLAIMCA

Specifies that the DASD space for empty control areas (CAs) will be reclaimed so that it can reused for that KSDS.

CA reclaim cannot reclaim space for:

Partially empty CAs
Empty CAs that already existed when CA reclaim was enabled
CAs with RBA 0
CAs with the highest key of the KSDS
Data sets processed with GSR.

NORECLAIMCA

Specifies that the DASD space for empty control areas (CAs) will not be reclaimed.

You can disable CA reclaim at the system level with the IGDSMSxx member of PARMLIB or with the SETSMS command. This does not change CA reclaim attributes in the catalog.

For more information, see the topic about reclaiming CA space in z/OS DFSMS Using Data Sets.

RECORDSIZE(average maximum)

Specifies new average and maximum lengths for data records contained in the object whose entry is being altered.

If the object whose entry is being altered is a path pointing to the alternate index, the alternate index is altered; if it is a path pointing directly to the base cluster, the base cluster is altered.

If the object whose entry is being altered is an alternate index, the length of the alternate key must be within the limit specified by maximum.

Restrictions: RECORDSIZE is used only if all the following are true:

The object whose entry is being altered is an alternate index, a cluster, a path, or a data component.
The object whose entry is being altered contains no data records.
The maximum RECORDSIZE in the object's catalog entry is the default. For defaults, see the DEFINE command for the object.
If NONUNIQUEKEY is used for an alternate index, the record length to be specified accounts for the increased record size; this results from the multiple prime key pointers in the alternate index data record.
Use a maximum record length of at least seven bytes less than the control interval size, unless the record is a spanned record.
Use a record length large enough to contain all prime and alternate keys previously defined.

If RECORDSIZE in the object's catalog entry is not the default, and ALTER RECORDSIZE specifies that same value, processing continues for any other parameters given in the command, and there is no error message.

Abbreviation: RECSZ

REMOVEVOLUMES(volser[ volser])

Specifies volumes to be removed from the list of candidate volumes associated with the entry being altered. The name of the data or index component must be specified in the ENTRYNAME parameter. If you are also adding volumes, the volumes to be removed are removed after the new volumes are added to the candidate list. Only nonspecific volumes can be removed from SMS-managed, non-VSAM data sets, and GDS data sets. For information on non-SMS managed volume cleanup, see "Removing All VSAM Data from a Volume" in z/OS DFSMS Managing Catalogs.

You cannot remove a Guaranteed Space candidate volume.

Abbreviation: RVOL

REUSE|NOREUSE

Controls setting the REUSE indicator for VSAM data sets. A data set that requires the REUSE attribute be changed to "reusable" cannot be an alternate index nor can it have an associated alternate index. The data set also cannot be a key-sequenced data set (KSDS) with one or more key ranges.

RLSQUIESE|RLSENABLE

Specifies whether the cluster's components be created in the RLS QUIESCE or ENABLE mode.

RLSQUIESCE: The cluster component will be defined in RLS QUIESCE mode. This is the default value.
Abbreviation: RLSQ
RLSENABLE: The cluster will be defined in RLS ENABLE mode.
Abbreviation: RLSE

ROLLIN

Indicates whether an SMS-managed generation data set (GDS) is to be rolled-in. The generation data set must be SMS managed and either in a deferred rolled-in state or a rolled-off state. For more information about rolling in GDSs, see z/OS DFSMS Using Data Sets for more information.

Abbreviation: ROL

SCRATCH|NOSCRATCH

Specifies whether generation data sets, when they are uncataloged, are to be removed from the VTOC of the volume where they reside.

SCRATCH: Removes the data set's format-1 DSCB from the VTOC so that the data set can no longer be accessed, and, for SMS-managed data sets, the non-VSAM volume record (NVR) is removed from the VVDS.
Abbreviation: SCR
NOSCRATCH: Indicates that the data set's format-1 DSCB is not to be removed from the VTOC and, for SMS-managed data sets, the NVR entry remains in the VVDS.
Abbreviation: NSCR

SHAREOPTIONS(crossregion[ crosssystem])

Is used when a data or index component of a cluster, alternate index, or the data component of a catalog can be shared among users. However, SMS-managed volumes, and catalogs containing SMS-managed data sets, must not be shared with non-SMS systems. (For a description of data set sharing, see z/OS DFSMS Using Data Sets).

The value of SHAREOPTIONS is assumed to be (3,3) when the data set is accessed in VSAM RLS or DFSMStvs mode.

crossregion

Specifies the amount of sharing allowed among regions within the same system or within multiple systems using global resource serialization (GRS). Independent job steps in an operating system, or multiple systems in a GRS ring, can access a VSAM data set concurrently. For a description of GRS, see z/OS MVS Planning: Global Resource Serialization. Option 3 is the only one applicable for altering a catalog. To share a data set, each user must code DISP=SHR in the data set's DD statement. You can use the following options:

OPT 1: The data set can be shared by any number of users for read processing, or the data set can be accessed by only one user for read and write processing. VSAM ensures complete data integrity for the data set. This setting does not allow any non-RLS access when the data set is already open for VSAM RLS or DFSMStvs processing. A VSAM RLS or DFSMStvs open will fail with this option if the data set is already open for any processing.
OPT 2: The data set can be accessed by any number of users for read processing, and it can also be accessed by one user for write processing. It is the user's responsibility to provide read integrity. VSAM ensures write integrity by obtaining exclusive control for a control interval while it is being updated. A VSAM RLS or DFSMStvs open is not allowed while the data set is open for non-RLS output.
If the data set has already been opened for VSAM RLS or DFSMStvs processing, a non-RLS open for input is allowed; a non-RLS open for output fails. If the data set is opened for input in non-RLS mode, a VSAM RLS or DFSMStvs open is allowed.
OPT 3: The data set can be fully shared by any number of users. The user is responsible for maintaining both read and write integrity for the data the program accesses. This setting does not allow any non-RLS access when the data set is already open for VSAM RLS or DFSMStvs processing. If the data set is opened for input in non-RLS mode, a VSAM RLS or DFSMStvs open is allowed.
This option is the only one applicable to a catalog.
OPT 4: The data set can be fully shared by any number of users. For each request, VSAM refreshes the buffers used for direct processing. This setting does not allow any non-RLS access when the data set is already open for RLS or DFSMStvs processing. If the data set is opened for input in non-RLS mode, a VSAM RLS or DFSMStvs open is allowed.
As in SHAREOPTIONS 3, each user is responsible for maintaining both read and write integrity for the data the program accesses.

crosssystem

Is the amount of sharing allowed among systems. Job steps of two or more operating systems can gain access to the same VSAM data set regardless of the disposition specified in each step's DD statement for the data set. To get exclusive control of the data set's volume, a task in one system issues the RESERVE macro. The level of cross-system sharing allowed by VSAM applies only in a multiple operating system environment.

The cross-system sharing options are ignored by VSAM RLS or DFSMStvs processing. The values are:

1: Reserved.
2: Reserved.
3: Specifies that the data set can be fully shared. With this option, each user is responsible for maintaining both read and write integrity for the data the program accesses. User programs that ignore write integrity guidelines can cause VSAM program checks, uncorrectable data set problems, and other unpredictable results. The RESERVE and DEQ macros are required with this option to maintain data set integrity. (For information on using RESERVE and DEQ, see z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU and z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN.)
4: Specifies that the data set can be fully shared. For each request, VSAM refreshes the buffers used for direct processing. This option requires that you use the RESERVE and DEQ macros to maintain data integrity while sharing the data set. Improper use of the RESERVE macro can cause problems similar to those described under SHAREOPTIONS 3. (For information on using RESERVE and DEQ, see z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU and z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN.) .)
Output processing is limited to update or add processing that does not change either the high-used relative byte address (RBA) or the RBA of the high key data control interval if DISP=SHR is specified.

Abbreviation: SHR

STORAGECLASS(class)

For SMS-managed data sets: Gives the name, 1 to 8 characters, of the storage class. Your storage administrator defines the names of the storage classes you can assign. A storage class is assigned when you specify STORAGECLASS or an installation-written automatic class section (ACS) routine selects a storage class when the data set is created. Use the storage class to provide the storage service level to be used by SMS for storage of the data set. The storage class provides the storage attributes that are specified on the UNIT and VOLUME operand for non-SMS-managed data sets.

When the storage or management class is altered for a DFSMShsm migrated data set, ALTER will not recall the data set to make the change, provided no other parameters are specified.

You must have RACF access authority to alter the storage class.

If STORAGECLASS is used for a non-SMS-managed data set or if SMS is inactive, the ALTER command is unsuccessful.

Abbreviation: STORCLAS

STRNO(number)

Specifies the number of concurrent catalog positioning requests that VSAM should manage. Use this parameter to alter the data component of a catalog. The STRNO setting is ignored when the data set is opened for RLS or DFSMStvs.

number: Is the number of concurrent requests VSAM must manage. The minimum number is 2, the maximum is 255.

SUSPEND|RESUME

Specifies suspension or resumption of catalog activity to a catalog. Catalog activity from unauthorized user(s) is suspended while the catalog is suspended. Catalog activity can be resumed via the IDCAMS ALTER command or CATALOG MODIFY command. See "MODIFY CATALOG Command Syntax" in z/OS DFSMS Managing Catalogs.

SUSPEND: Specifies that requests for this catalog will be suspended until a RESUME is issued via the F CATALOG,RECOVER,RESUME or ALTER RESUME command is issued.
Abbreviation: SUSPD
RESUME: Specifies that requests for this catalog resume following a DEFINE ALTER or F CATALOG,RECOVER,RESUME command.
Abbreviation: RESUM

TO(date)|FOR(days)

Specifies the retention period for the entry being altered.

You cannot use these parameters for the data or index components of clusters or alternate indexes. For catalogs, you must use the data component name. The expiration date in the catalog is updated, and, for SMS-managed data sets, the expiration date in the format-1 DSCB is changed. Enter a LISTCAT command to see the correct expiration date.

The MANAGEMENTCLASS maximum retention period, if specified, limits the retention period specified by this parameter.

TO(date)

Specifies the earliest date that a command without the PURGE parameter can delete an entry. Specify the expiration date in the form yyyyddd, where yyyy is a four-digit year (to a maximum of 2155) and ddd is the three-digit day of the year from 001 through 365 (for non-leap years) or 366 (for leap years).

The following four values are "never-expire" dates: 99365, 99366, 1999365, and 1999366. Specifying a "never-expire" date means that the PURGE parameter will always be required to delete an entry. For related information, see the "EXPDT Parameter" section of z/OS MVS JCL Reference.

Note:

Any dates with two-digit years (other than 99365 or 99366) will be treated as pre-2000 dates. (See note 2.)
Specifying the current date or a prior date as the expiration date will make an entry immediately eligible for deletion.

FOR(days)

Specifies the number of days you want to keep the entry. The maximum number is 93000. If the number is 0 through 92999 (except for 9999), the entry is retained for the number of days indicated. If the number is either 9999 or 93000, the entry is retained indefinitely. There is a hardware imposed expiration date of 2155.

TYPE(LINEAR)

Specifies that the VSAM data set type of an entry-sequenced data set (ESDS) is to be changed to linear. The contents of the data set are not modified. Only an ESDS with a CI size of 4096 is eligible to be a linear data set. A linear data set's type cannot be changed. After you have changed an ESDS set to a linear data set, the data set must remain a linear data set; you cannot change it back into an ESDS.

LINEAR: Changes the VSAM data type ESDS to a linear data set (LDS).
Abbreviation: LIN

UNIQUEKEY|NONUNIQUEKEY

Specifies whether the alternate key value can be found in more than one of the base cluster's data records.

UNIQUEKEY

Makes each alternate key value unique. If the same alternate key value is found in more than one of the base cluster's data records, an error results.

You can use UNIQUEKEY for an empty alternate index (that is, an alternate index that is defined but not yet built).

Abbreviation: UNQK

NONUNIQUEKEY

Allows an alternate key value to point to more than one data record in the cluster. NONUNIQUEKEY can be specified for an alternate index at any time.

If the alternate index is empty, you should also consider defining RECORDSIZE to ensure that each alternate index record is large enough to contain more than one data record pointer.

Abbreviation: NUNQK

UPDATE|NOUPDATE

Specifies whether a base cluster's alternate index upgrade set is to be allocated when the path's name is allocated.

The NOUPDATE setting is ignored when the data set is opened for VSAM RLS or DFSMStvs. Alternate indexes in the upgrade set are opened as if UPDATE was specified.

UPDATE: Allocates the cluster's alternate index upgrade set when the path's name is allocated with a DD statement.
Abbreviation: UPD
NOUPDATE: Specifies that the cluster's alternate index upgrade set is not to be allocated but the path's cluster is to be allocated. You can use NOUPDATE to open a path. If the path shares a control block structure that uses UPDATE, this indicates the upgrade set has been allocated and, in this case, the upgrade set can be updated.
Abbreviation: NUPD

UPGRADE|NOUPGRADE

Shows whether an alternate index is to be upgraded (to reflect the changed data) when its base cluster is modified.

UPGRADE

Indicates that the cluster's alternate index is upgraded (to reflect the changed data) when the cluster's records are added to, updated, or erased. If UPGRADE is used when the cluster is open, the upgrade attribute does not apply to the alternate index until the cluster is closed and then opened (that is, a new set of VSAM control blocks describes the cluster and its attributes).

Use UPGRADE for an empty alternate index (that is, an alternate index that is defined but not built). However, the UPGRADE attribute is not effective for the alternate index until the alternate index is built (see the description of the BLDINDEX command).

Abbreviation: UPG

NOUPGRADE

Specifies the alternate index is not to be modified when the its base cluster is modified. NOUPGRADE can be use as an alternate index at any time.

Abbreviation: NUPG