Optional parameters

ACCOUNT(account–info)

Account is supported only for SMS-managed VSAM data sets 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 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 general data stream (GDS) data sets. 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 on-line before attempting to extend the data set.

Restriction: This does not work with NONSMS NONVSAM

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 the 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 RLS 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, but must not exceed 16,776,704. 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.

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. Use this parameter only to alter the data component of an integrated catalog facility catalog.

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

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

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. Use this parameter only to alter the index component of the integrated catalog facility catalog.

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

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, LOG, or LOGSTREAMID is specified (or an RLS cell exists for the data set), access from DFSMS/MVS 1.2 or a lower-level system is denied.

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® or DFSMStvs 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 FCT. For more information about the use of TYPECICS, see the CICS Transaction Server for z/OS Information Center at http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/index.jsp.

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: Enables BWO processing for IMS™ data sets. You can use this capability only with DFSMS 1.3 or higher-level DFSMS systems. If you attempt to open a cluster that has the TYPEIMS specification of a DFSMS 1.2 (or lower-level) system, the open will not be successful.
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. For more information, seez/OS DFSMS Access Method Services Commands.

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'n'), or binary (B'n'). 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 method of catalog sharing that makes use of a coupling facility to increase the performance of shared catalog requests. Read about ECS in z/OS DFSMS Managing Catalogs before enabling it 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 has been cataloged. If the GDG is full (the LIMIT is reached), this attribute determines whether all GDSs or just the oldest GDSs are processed.

For an SMS-managed generation data set, 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 generation data sets is exceeded, all the generation data sets are uncataloged or deleted.
Abbreviation: EMP
NOEMPTY: Used when the maximum number of generation data sets is exceeded, only the oldest generation data set 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

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.

Note: 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])

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

Abbreviation: FSPC

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

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 RLS or DFSMStvs is recoverable or nonrecoverable. It also indicates whether a recovery log is available 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 and update sharing for nonrecoverable spheres through commit (CICS) and noncommit protocol applications. For a recoverable sphere, a noncommit protocol application must use DFSMStvs to be able to open the sphere for update using RLS access.

Restriction: LOG cannot be used with LINEAR.

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).
For information about defining log streams for CICS use, see the CICS Transaction Server for z/OS Information Center at http://publib.boulder.ibm.com/infocenter/cicsts/v3r1/index.jsp.

Abbreviation: LSID

Restriction: LOGSTREAMID cannot be used with LINEAR.

LIMIT(limit)

Used to modify the maximum number (between 1 and 255) of active generation data sets that might be associated with a generation data group 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 generation data sets 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.

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 an integrated catalog facility catalog. If the LOCK|UNLOCK parameter is not specified, the status of the integrated catalog facility 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: You cannot alter the data portion of a page space data set to a new name. Also, 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. This table shows 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.

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 using ALTER NEWNAME, you must have one of these:
- ALTER authority for the data set or for the catalog
- ALTER authority for the new name (generic profile) 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 are to 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.

Access to the RLS 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

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.

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 volume cleanup, see z/OS DFSMS Managing Catalogs.

SMS might not use candidate volumes for which you request specific volsers. Some user-specified volsers for an SMS-managed data set can result in an error. To avoid candidate volume problems with SMS, you can request that SMS choose the given volser used for a candidate volume. To do this, you can code an * for each volser that you request. If, however, you request both specified and unspecified volsers in the same command, you must enter the specified volsers first in the command syntax.

To ensure that the operation has completed correctly, the execution of ALTER REMOVEVOLUMES should be followed by a listing of the VTOC on the target volume. If ALTER REMOVEVOLUMES did not scratch any data sets allocated to job steps, it can still complete with return code zero. In the integrated catalog facility environment, both the basic catalog structure (BCS) and the VSAM volume data set (VVDS) might be allocated to another job or TSO/E user. If so, these entities are not scratched, and any future access method services commands that depend on ALTER REMOVEVOLUMES completing normally might be unsuccessful. To ensure that the operation has completed correctly, follow the execution of ALTER REMOVEVOLUMES with a listing of the VTOC on the target volume.

Exceptions:

If a volume to be removed contains data that belongs to the entry being altered, the volume is not removed.
Volume cleanup is not supported if the volume is SMS managed.

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.

ROLLIN

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

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 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 follow:

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 ALE-DYN and z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU.)
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 ALE-DYN and z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU.)
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.

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 date up to which an entry should be kept before it is allowed to be deleted. The date is specified in the form [yy]yyddd, where yyyy is a four-digit year, yy is a two-digit year, and ddd is the three-digit (001 through 366) day of the year. Two-digit years are treated as if "19" is specified as the first two digits of yyyy. The dates (19)99365 and (19)99366 are considered never-expire dates.
For expiration dates of January 1, 2000, and later, you must use the form TO(yyyyddd).
FOR(days): Is used to choose the number of days to keep the entry. The maximum number is 9999. If the number is 0 through 9998, the entry is retained for the number of days indicated; if the number is 9999, the entry is retained indefinitely.

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

WRITECHECK|NOWRITECHECK

Specifies whether a data or index component is to be checked by a machine action called write check when a record is written into it. This parameter can be specified to alter the data or index components of a cluster, an alternate index, or catalog.

The WRITECHECK setting is ignored when the data set is opened for VSAM RLS or DFSMStvs access.

WRITECHECK: Writes and reads a record without data transfer, to test for the data check condition.
Abbreviation: WCK
NOWRITECHECK: Writes the record only
Abbreviation: NWCK