The DEFINE CLUSTER command can execute the following optional parameters.

ACCOUNT(account–info)

Defines up to 32 bytes of accounting information and user data for the data set. It must be between 1 and 32 bytes; otherwise, you will receive an error message.

account–info

Is supported only for SMS-managed VSAM and non–VSAM data sets. It is used only for the data set level (not member level) of PDSE/PDS.

Abbreviation: ACCT

BUFFERSPACE(size)

Specifies the minimum space for buffers. The buffer space size helps VSAM determine the data component's and index component's control interval size. If BUFFERSPACE is not coded, 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.

If the data set being defined is a KSDS, and the BUFFERSPACE specified is not large enough to contain two data and one index CI's, VSAM increases the specified buffer space and completes the define. VSAM also increases index CISIZE and, if necessary, increases the buffer space to accommodate the larger index CISIZE.

size

Is the space for buffers. Size can be given in decimal (n), hexadecimal (X'n'), or binary (B'n') form, but must not exceed 16,776,704.

The size cannot be less than enough space to contain two data component control intervals and, if the data is key sequenced, one index control interval. If size is too small for VSAM buffers, VSAM ends your DEFINE and provides an appropriate error message.

Note: The BUFFERSPACE setting is ignored when the data set is opened for VSAM RLS or DFSMStvs mode.

Abbreviations: BUFSP or BUFSPC

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 z/OS DFSMSdfp Storage Administration and 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)

Identifies the catalog in which the cluster is to be defined.

Before you can specify catalog names for SMS-managed data sets, you must have authority for the RACF® STGADMIN.IGG.DIRCAT facility class. For the order in which catalogs are selected and more information, see z/OS DFSMS Access Method Services Commands.

catname

Is the name of the catalog in which the entry is to be defined.

If the catalog's volume is physically mounted, it is dynamically allocated. The volume must be mounted as permanently resident or reserved.

Abbreviation: CAT

CONTROLINTERVALSIZE(size)

Specifies the size of the control interval for the cluster or component.

For linear data sets, the specified value in bytes is rounded up to a 4K multiple, up to a maximum of 32K. If the size is not specified, the value specified in the data class that is assigned to the data set is used. Otherwise a default value of 4K is used.

If CONTROLINTERVALSIZE is given on the cluster level, it propagates to the component level at which no CONTROLINTERVALSIZE has been specified.

The size of the control interval depends on the maximum size of the data records and the amount of buffer space you provide.

LSR/GSR buffering technique users can ensure buffer pool selection by explicitly defining data and index control interval sizes.

If CONTROLINTERVALSIZE is not coded, VSAM determines the size of control intervals. VSAM selects a control interval size for the data component that will optimize direct access storage usage. It will then select an index control interval size based on the number of data control intervals in the data control area.

size

Indicates a cluster's data and index component size.

If SPANNED is not used, the size of a data control interval must be at least 7 bytes larger than the maximum record length.

If the control interval specified is less than maximum record length plus a 7-byte overhead, VSAM increases the data control interval size to contain the maximum record length plus the needed overhead.

If SPANNED is specified, the control interval size can be less than the maximum record length. You can select a size from 512 to 8K in increments of 512, or from 8K to 32K in increments of 2K. When you choose a size that is not a multiple of 512 or 2048, VSAM chooses the next higher multiple. For a linear data set, the size specified is rounded up to 4096 if specified as 4096 or less. It is rounded to the next higher multiple of 4096 if specified as greater than 4096.

The size of the index control interval is the number of data control intervals in a data control area that need indexing at the sequence set level of the index component. The size of each entry depends on an average compression value for a user key. The keys will compress to 1/3 of the length of the actual key value. In some cases, the general compressed key length on which the algorithm is based will be affected by the actual values and ordering of the user key. The result is that each entry can occupy more space in the index record than that provided. This may result in additional control area splits and in all cases, wasted space in the data set. If after loading the data sets, this condition exists; noted by more than anticipated space to store the data set on the direct access device. You should increase the index control interval size. The size can be increased incrementally until it is felt that this condition no longer exists. The guideline formula documented in the past is as follows:

(KEYLEN/2 ) * DATA CI/CA less than or equal to INDEX CISIZE.

You should be aware that this is only a guideline and does not take into account the actual algorithm for determining the index control interval size requirement. However, the 2:1 compression of key length in this formula provides some additional overhead over the actual 3:1 formula used during the actual algorithm. Using this formula can result in an index control interval size that is too large. This may increase I/O transfer time for each index component record, or it may be too small to address these conditions.

For a discussion of control interval size and physical block size, see z/OS DFSMS Using Data Sets.

Abbreviation: CISZ or CNVSZ

DATACLASS(class)

Identifies the name, 1 to 8 characters, of the data class for the data set. It provides the allocation attributes for new data sets. Your storage administrator defines the data class. However, you can override the parameters defined for DATACLASS by explicitly using other attributes. See z/OS DFSMS Access Method Services Commands for the order of precedence (filtering) the system uses to select which attribute to assign.

DATACLASS parameters apply to both SMS-managed and non-SMS-managed data sets. If DATACLASS is specified and SMS is inactive, DEFINE is unsuccessful.

DATACLASS cannot be used as a subparameter of DATA or INDEX.

Abbreviation: DATACLAS

ERASE|NOERASE

Specifies whether the cluster's components are to be erased when its entry in the catalog is deleted.

ERASE

Overwrites each component of the cluster with binary zeros when its catalog entry is deleted. If the cluster is protected by a RACF generic or discrete profile and is cataloged in an integrated catalog facility catalog, you can use RACF commands to specify an ERASE attribute. If you do this, the data component is automatically erased upon deletion.

Abbreviation: ERAS

NOERASE

Specifies that each component of the cluster is not to be overwritten with binary zeros. NOERASE will not prevent erasure if the cluster is protected by a RACF generic or discrete profile that specifies the ERASE attribute and if the cluster is cataloged in a catalog. Use RACF commands to alter the ERASE attribute in a profile.

Abbreviation: NERAS

EXCEPTIONEXIT(entrypoint)

Specifies the name of a user-written exception-exit routine, that receives control when an exceptional I/O error condition occurs during the transfer of data between your program's address space and the cluster's DASD space. An exception is any condition that causes a SYNAD exit to be taken. The component's exception-exit routine is processed first, then the user's SYNAD exit routine receives control. If an exception-exit routine is loaded from an unauthorized library during access method services processing, an abnormal termination occurs. See z/OS DFSMS Using Data Sets.

Abbreviation: EEXT

FILE(ddname)

Names the DD statement that identifies and allocates the DASD and volumes that must be available for space allocation on the volumes specified by the VOLUMES keyword. If more than one volume is specified, all volumes must be the same device type.

If data and index components are to reside on separate devices, you can specify a separate FILE parameter as a parameter of DATA and INDEX to point to different DD statements.

If the FILE parameter is not specified, an attempt is made to dynamically allocate the required volumes. The volume must be mounted as permanently resident or reserved. When the FILE parameter is used, the specified volumes are directly allocated before access method services gets control.

An example DD statement is:

 //ddname DD UNIT=(devtype[,unitcount]),
 //    VOL=SER=(volser1,volser2,volser,...),DISP=OLD

Restriction: When FILE refers to more than one volume of the same device type, the DD statement that describes the volumes cannot be a concatenated DD statement.

FREESPACE(CI-percent[ &cont; CA-percent]|0 0)

Specifies the percentage of each control interval and control area to be set aside as free space when the cluster is initially loaded or when a mass insert is done. 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 empty space in the control interval and control area is available for data records that are updated and inserted after the cluster is initially loaded. This parameter applies only to key-sequenced clusters, and variable-length relative records with variable-length records. CI-percent is the number of bytes that is equal to, or slightly less than, the percentage value of CI-percent. CA-percent is the number of control intervals equal to, or less than, the percentage of CA-percent.

CI-percent and CA-percent must be equal to, or less than, 100. When you use FREESPACE(100 100), one data record is placed in each control interval used for data. One control interval in each control area is used for data (that is, one data record is stored in each control area when the data set is loaded). If you do not use FREESPACE, the default reserves no free space when the data set is loaded.

When you define the cluster using the RECORDS parameter, the amount of free space specified is not considered in the calculations to determine primary allocation.

Abbreviation: FSPC

FRLOG(NONE|REDO)

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

There is no default value for FRLOG. If FRLOG is left out, the data set cannot be used for VSAM batch logging. See the ALTER command for enabling VSAM batch logging after a data set is created.

NONE

Indicates that the data set can be used for VSAM batch logging. However, the function should be disabled. The LOGSTREAMID parameter indicates changes that are made by applications that are written to the MVS™ log stream. Specifying FRLOG(NONE) implies that you can use the data set for RLS processing; omitting it indicates that RLS processing will not occur.

REDO

Enables the VSAM batch logging function for your VSAM data set. The LOGSTREAMID parameter indicates changes that are made by applications that are written to the MVS log stream. When specifying FRLOG(REDO), you must also specify LOGSTREAMID.

Restrictions:

1. If you do not want VSAM batch logging for your data set, do not specify the FRLOG parameter. If you specify FRLOG(NONE), the data set must support VSAM batch logging, but logging is not in effect.
2. If FRLOG is specified, the following restrictions apply:
   • The data set must be SMS-managed.
   • The data set cannot be a linear or temporary data set.

INDEXED|LINEAR|NONINDEXED|NUMBERED

Shows the type of data organization for the cluster.

If you want a data organization other than INDEXED (the default), you must explicitly use it with this parameter.

When a cluster is defined, you indicate whether the data is to be indexed (key sequenced), nonindexed (entry sequenced), numbered (relative record), or linear.

Certain parameters apply only to key-sequenced clusters, as noted in the description of each of these parameters.

Linear data set clusters are treated as ESDS clusters that must be processed using control interval access.

If you do not choose either the data organization or the MODEL parameter, your cluster defaults to key-sequenced (indexed).

If you want to define an entry-sequenced or a relative record cluster, you must specify the NONINDEXED, the NUMBERED, or the MODEL parameter.

The data organization you select must be consistent with other parameters you specify.

INDEXED

Shows that the cluster being defined is for key-sequenced data. If INDEXED is specified, an index component is automatically defined and cataloged. The data records can be accessed by key or by relative-byte address (RBA).

Abbreviation: IXD

LINEAR

Specifies that the cluster being defined is for linear data. Because linear data set clusters are treated as ESDS clusters that must be processed using control interval access, you can use most of the commands and parameters you use to manipulate ESDS clusters. There are two exceptions:

• Parameters that refer to logical records are not allowed (except RECORDS).
• Use partial printing by specifying the RBA syntax.

Space is allocated for a linear data set with the number of control intervals equal to the number of records.

Restriction: Linear data sets cannot be accessed for VSAM RLS or DFSMStvs processing. The LOG, LOGSTREAMID, and BWO parameters do not apply to linear data sets.

Abbreviation: LIN

NONINDEXED

Indicates that the cluster being defined is for entry-sequenced data. The data records can be accessed sequentially or by relative-byte address (RBA).

Abbreviation: NIXD

NUMBERED

Specifies that the cluster's data organization is for relative record data. A relative record cluster, which is similar to an entry-sequenced cluster, has fixed-length records or variable-length records that are stored in slots. The RECORDSIZE parameter determines if the records are fixed-length or variable-length. Empty slots hold space for records to be added later. The data records are accessed by relative record number (slot number).

Abbreviation: NUMD

KEYS(length  offset|64 0)

gives information about the prime key field of a key-sequenced data set's data records.

This parameter overrides any KEYS specification in the DATACLASS parameter.

This parameter applies only to key-sequenced clusters. The default is a key field of 64 bytes, beginning at the first byte (byte 0) of each data record.

The key field of the cluster's index is called the prime key to distinguish it from other keys, called alternate keys. See Defining alternate indexes for more details on how to choose alternate indexes for a cluster.

When the data record spans control intervals, the record's key field must be within the part of the record that is in the first control interval.

length  offset

Specifies the length of the key and its displacement (in bytes) from the beginning of the record. The sum of length plus offset cannot exceed the length of the shortest record. The length of the key can be 1 to 255 bytes.

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 forward recovery log is available for the sphere. LOG applies to all components in the VSAM sphere. VSAM uses LOG in the following way:

Nonrecoverable Sphere

The sphere is considered nonrecoverable if LOG(NONE) is specified. VSAM allows concurrent read and update sharing across multiple resource managers and other applications.

Recoverable Sphere

The sphere is considered recoverable if LOG(UNDO) or LOG(ALL) is specified. For a recoverable sphere, VSAM does not allow applications that do not support commit and backout to open a data set in the sphere for output using RLS access, but applications can open the sphere for output using DFSMStvs access. The applications can, however, open the sphere for RLS access for input processing only.

If the LOG parameter is not specified, the value in the catalog is undefined. RLS and DFSMStvs OPEN of the data set is not allowed unless the LOG parameter has been specified.

If BWO, LOG, or LOGSTREAMID is specified (or an RLS cell exists for the data set), access from DFSMS/MVS 1.2 or lower-level systems is denied.

If LOG is specified in the SMS data class, the value defined is used as the data set definition, unless it has been previously defined with an explicitly specified or modeled DEFINE attribute.

LOG cannot be used with LINEAR.

LOGSTREAMID cannot be used with LINEAR.

NONE

Indicates that neither an external backout nor a forward recovery capability is available for the sphere accessed in VSAM RLS or DFSMStvs mode. If you use LOG(NONE), 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. RLS and DFSMStvs consider the sphere to be recoverable when you use LOG(UNDO).

ALL

Specifies that changes to the sphere accessed in RLS and DFSMStvs mode can be backed out and forward recovered using external logs. DFSMStvs and RLS consider the sphere recoverable when you use LOG(ALL). When you specify LOG(ALL), you must also specify the LOGSTREAMID parameter.

VSAM RLS and DFSMStvs allow concurrent read or 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.

LOGSTREAMID(logstream)

Gives the name of the forward recovery log stream. It applies to all components in the VSAM sphere. This parameter is used when the cluster is accessed with MACRF=RLS.

If BWO, LOG, or LOGSTREAMID is specified (or an RLS cell exists for the data set), access from DFSMS/MVS 1.2 or lower-level systems is denied.

If LOGSTREAMID is specified in the SMS data class, the value defined is used as the data set definition, unless it has been previously defined with an explicitly specified or modeled DEFINE attribute.

logstream

Is the name of the forward recovery log stream. This can be a fully qualified name up to 26 characters, including separators. If LOG(ALL) is specified, LOGSTREAMID(name) must be specified. 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

Note: LOGSTREAMID cannot be used with LINEAR.

MANAGEMENTCLASS(class)

For SMS-managed data sets, specifies the name, 1 to 8 characters, of the management class for a new data set. Your storage administrator defines the names of the management classes you can use. If MANAGEMENTCLASS is not used, but STORAGECLASS is used or defaulted, MANAGEMENTCLASS is derived from automatic class selection (ACS). If MANAGEMENTCLASS is specified and STORAGECLASS is not specified or derived, the DEFINE is unsuccessful. If SMS is inactive and MANAGEMENTCLASS is specified, the DEFINE will be unsuccessful. MANAGEMENTCLASS cannot be listed as a subparameter of DATA or INDEX.

Abbreviation: MGMTCLAS

MODEL(entryname[ catname])

Specifies an existing entry to be used as a model for the entry being defined. See z/OS DFSMS Access Method Services Commands for information on how the system selects modeled attributes.

A VVDS cannot be modeled.

The DATACLASS, MANAGEMENTCLASS, and STORAGECLASS attributes are not modeled.

You can use an existing cluster's entry as a model for the attributes of the cluster being defined. For details about how a model is used, see z/OS DFSMS Managing Catalogs.

You can use some attributes of the model and override others by explicitly specifying them in the definition of the cluster or component. If you do not want to add or change any attributes, you need specify only the entry type (cluster, data, or index) of the model to be used and the name of the entry to be defined.

See z/OS DFSMS Access Method Services Commands for more information about the order in which the system selects an attribute.

When you use a cluster entry as a model for the cluster, the data and index entries of the model cluster are used as models for the data and index components of the cluster still to be defined, unless another entry is specified with the MODEL parameter as a subparameter of DATA or INDEX.

entryname

Specifies the name of the cluster or component entry to be used as a model.

catname

Names the model entry's catalog. You identify the catalog that contains the model entry if the model entry's catalog is not identified with a JOBCAT or STEPCAT DD statement, and is not the master catalog.

If a catalog's volume is physically mounted, it is dynamically allocated. The volume must be mounted as permanently resident or reserved. For information about the order in which a catalog is selected when the catalog name is not specified, see z/OS DFSMS Access Method Services Commands.

FRLOG(NONE|REDO)

Option to request that VSAM interface with CICSVR to log changed data to an MVS Log Stream. The log data and a previous HSM backup can be used for forward recovery.

NONE

Specifies that the forward recovery capability is not available for the sphere.

REDO

Specifies that the forward recovery capability is available for the sphere. Batch logging is supported for NSR, LSR, and GSR and does not require modification of application programs. When you specify FRLOG(REDO), you must also specify the LOGSTREAMID parameter.

Note:

1. FRLOG cannot be used with LINEAR.
2. This support is available with CICSVR 2.4

OWNER(ownerid)

identifies the cluster's owner.

For TSO/E users, if the owner is not identified with the OWNER parameter, the TSO/E user's userid becomes the ownerid.

RECATALOG|NORECATALOG

Indicates whether the catalog entries for the cluster components are to be re-created from information in the VVDS.

RECATALOG

Re-creates the catalog entries if valid VVDS entries are found on the primary VVDS volume. If they are not, the command ends.

Catalog entries can be re-created only in the catalog specified in the VVR except for entries that are swap space, page space, or SYS1 data sets.

The RECORDSIZE parameter is required when doing a DEFINE RECATALOG of a variable-length relative record data set (VRRDS).

Identification of RECATALOG requires that NAME, INDEXED, LINEAR, NONINDEXED, NUMBERED, and VOLUMES be used as they were when the cluster was originally defined. If you specify RECATALOG, you are not required to use CYLINDERS, RECORDS, or TRACKS.

If the ATTEMPTS, AUTHORIZATION, CATALOG, CODE, FOR, MODEL, OWNER, or TO parameter is used during the original define, they must be respecified with RECATALOG to restore their original values; otherwise, their default values are used.

When you use the TO parameter with RECATALOG, only the cluster's expiration date is updated. The DATA and INDEX components are not updated.

If the RACF user has ADSP specified, a profile is defined to RACF for the data set being recataloged.

If the cluster was SMS-managed, the volume serials should be the same as the volumes actually selected by SMS.

The catalog for the entries being re-created must have the same name as the catalog that contained the original entries.

Abbreviation: RCTLG

NORECATALOG

Indicates that the catalog entries are not re-created from VVDS entries. Catalog entries are created for the first time.

Abbreviation: NRCTLG

RECORDSIZE(average  maximum|default)

Specifies the average and maximum lengths, in bytes, of the records in the data component. The minimum record size is 1 byte.

RECORDSIZE can be given as a parameter of either CLUSTER or DATA.

This parameter overrides the LRECL specification on the DATACLASS parameter.

For nonspanned records, the maximum record size + 7 cannot exceed the data component's control interval size (that is, the maximum nonspanned record size, 32761, + 7 equals the maximum data component control interval size, 32768).

When you use a record size that is larger than one control interval, you must also specify spanned records (SPANNED). The formula for the maximum record size of spanned records as calculated by VSAM is as follows:

MAXLRECL = CI/CA * (CISZ - 10)

where:

• MAXLRECL is the maximum spanned record size.
• CI/CA represents the number of control intervals per control area.
• CA is the number of control areas.
• CISZ is the quantity control interval size.

When you select NUMBERED, you identify a data set as a relative record data set. If you use NUMBERED and select the same value for average as for maximum, the relative records must be fixed-length. If you specify NUMBERED and select two different values for the average and maximum record sizes, the relative records can be variable-length. If you know that your relative records are fixed-length, however, be sure to define them as fixed-length. Performance is affected for relative record data sets defined as variable-length. Each variable-length relative record is increased internally in length by four.

When your records are fixed length, you can use the following formula to find a control interval size that contains a whole number (n) of records:

CISZ = (n x RECSZ) + 10
or
n = (CISZ - 10)
       RECSZ

If you select SPANNED or NUMBERED for your fixed-length records:

CISZ =(n x (RECSZ + 3)) + 4
or
n = (CISZ - 4)
    (RECSZ + 3)

Variables in the example represent these values:

• n is the number of fixed-length records in a control interval.
• CISZ is the control interval size (see also the CONTROLINTERVALSIZE parameter).
• RECSZ is the average record size.

default

When SPANNED is used, the default is RECORDSIZE(4086 32600). Otherwise, the default is RECORDSIZE(4089 4089).

Important:

REC(sec) x RECSZ(avg) > RECSZ(max) 

• Variables in the example represent these values:
  • REC(sec) is the secondary space allocation quantity, in records.
  • RECSZ(avg) is the average record size (default = 4086 or 4089 bytes).
  • RECSZ(max) is the maximum record size (default = 4089 or 32600 bytes).

When the SPANNED record size default prevails (32600 bytes), the secondary allocation quantity should be at least 8 records.

Restriction: REPRO and EXPORT do not support data sets with record sizes greater than 32760.

Abbreviation:RECSZ

REUSE|NOREUSE

Specifies whether the cluster can be opened again and again as a reusable cluster.

If REUSE or NOREUSE is specified in the SMS data class, the value defined is used as the data set definition, unless it has been previously defined with an explicitly specified or modeled DEFINE attribute.

REUSE

Specifies that the cluster can be opened again and again as a reusable cluster. When a reusable cluster is opened, its high-used RBA is set to zero if you open it with an access control block that specifies the RESET attribute.

REUSE lets you create an entry-sequenced, key-sequenced, or relative-record work data set.

When you create a reusable cluster, you cannot build an alternate index to support it. Also, you cannot create a reusable cluster with key ranges. Reusable data sets can be multivolume and can have up to 123 physical extents.

Restriction: If you select REUSE and your command also contains the keyword UNIQUE, you must remove the UNIQUE keyword or the DEFINE command will be unsuccessful.

Abbreviation: RUS

NOREUSE

indicates that the cluster cannot be opened again as a new cluster.

Abbreviation: NRUS

SHAREOPTIONS(crossregion[ &cont; crosssystem]|1 3)

Shows how a component or cluster 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. To ensure integrity, you should be sure that share options specified at the DATA and INDEX levels are the same.

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 more information about GRS, see z/OS MVS Planning: Global Resource Serialization. To share a data set, each user must use 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. Each 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.

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

As in SHAREOPTIONS 3, each user is responsible for maintaining both read and write integrity for the data the program accesses.

crosssystem

Specifies 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 indicated in each step's DD statement for the data set. However, if you are using GRS across systems or JES3, the data set might not be shared depending on the disposition of the system.

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 that user's program accesses. User programs that ignore write integrity guidelines can cause VSAM program checks, uncorrectable data set errors, and other unpredictable results. This option requires each user to be responsible for maintenance. 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

Indicates 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, or both that does not change either the high-used RBA or the RBA of the high key data control interval if DISP=SHR is specified.

To ensure data integrity in a shared environment, VSAM provides users of SHAREOPTIONS 4 (cross-region and cross-system) with the following assistance:

• Each PUT request immediately writes the appropriate buffer to the VSAM cluster's DASD space. That is, the buffer in the user's address space that contains the new or updated data record, and the buffers that contain new or updated index records when the user's data is key-sequenced.
• Each GET request refreshes all the user's input buffers. The contents of each data and index buffer being used by the user's program is retrieved from the VSAM cluster's DASD.

Abbreviation: SHR

SPANNED|NONSPANNED

Specifies whether a data record is allowed to cross control interval boundaries.

If SPANNED or NONSPANNED is specified in the SMS data class, the value defined is used as the data set definition, unless it has been previously defined with an explicitly specified or modeled DEFINE attribute.

This parameter cannot be used when defining a linear data set cluster.

SPANNED

Specifies that, if the maximum length of a data record (as specified with RECORDSIZE) is larger than a control interval, the record is contained on more than one control interval. This allows VSAM to select a control interval size that is optimum for the DASD.

When a data record that is larger than a control interval is put into a cluster that allows spanned records, the first part of the record completely fills a control interval. Subsequent control intervals are filled until the record is written into the cluster. Unused space in the record's last control interval is not available to contain other data records.

Attention: Using this parameter for a variable-length relative record data set causes an error.

Abbreviation: SPND

NONSPANNED

Indicates that the record must be contained in one control interval. VSAM selects a control interval size that accommodates your largest record.

Abbreviation:NSPND

SPEED|RECOVERY

Specifies whether the data component's control areas are to be preformatted before alternate index records are loaded into them.

This parameter is only considered during the actual loading (creation) of a data set. Creation occurs when the data set is opened and the high-used RBA is equal to zero. After normal CLOSE processing at the completion of the load operation, the physical structure of the data set and the content of the data set extents are exactly the same. Any processing of the data set after the successful load operation is the same, and the specification of this parameter is not considered.

If you use RECOVERY, the initial load takes longer because the control areas are first written with either empty or software end-of-file intervals. These preformatted CIs are then updated, using update writes, with the alternate index records. SPEED is recommended, because the initial load is quicker.

SPEED

Does not preformat the data component's space.

If the initial load is unsuccessful, you must load the alternate index records again from the beginning, because VSAM cannot determine the location of your last correctly written record. VSAM cannot find a valid end-of-file indicator when it searches your alternate index records.

RECOVERY

Specifies that the data component's control areas are written with records that indicate end-of-file. When an alternate index record is written into a control interval, it is always followed by a record that identifies the record just written as the last record in the alternate index.

RECOVERY is a way to verify storage that is used on the device for each CA before the data is actually written.

Abbreviation: RCVY

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 use. A storage class is assigned either when you use STORAGECLASS, or an ACS routine selects a storage class for the new data set. The storage class provides the storage attributes that are specified on the UNIT and VOLUME operand for non-SMS managed data sets. Use the storage class to select the storage service level to be used by SMS for storage of the data set. If SMS is inactive and STORAGECLASS is used, the DEFINE will be unsuccessful.

STORAGECLASS cannot be selected as a subparameter of DATA or INDEX.

Abbreviation: STORCLAS

TO(date)|FOR(days)

Specifies the retention period for the cluster being defined. If neither TO nor FOR is used, the cluster can be deleted at any time. The MANAGEMENTCLASS maximum retention period, if selected, limits the retention period specified by this parameter.

For non-SMS-managed data sets, the correct retention period is reflected in the catalog entry. The VTOC entry cannot contain the correct retention period. Enter a LISTCAT command for the correct expiration date.

For SMS-managed data sets, the expiration date in the catalog is updated and the expiration date in the format-1 DSCB is changed. If the expiration date in the catalog does not agree with the expiration date in the VTOC, the VTOC entry overrides the catalog entry.

TO(date)

Specifies the date up to which to keep the cluster before it is allowed to be deleted. The date is given in the form [yy]yyddd, in which yyyy is a four-digit year, yy is a two-digit year, and ddd is a three-digit day of the year (001 through 366). 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).

The maximum value of yyyy is 2155, and the maximum value of ddd is 365 for nonleap years and 366 for leap years.

FOR(days)

Shows the number of days to keep the cluster being defined. The maximum number is 9999. If the number is 0 through 9998, the cluster is retained for the number of days; if the number is 9999, the cluster is retained indefinitely.

WRITECHECK|NOWRITECHECK

Indicates whether the cluster or component is to be checked by a machine action called write check when a record is written into it.

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

WRITECHECK

Shows that a record is written and then read, without data transfer, to test for the data check condition.

Abbreviation: WCK

NOWRITECHECK

Specifies that the cluster or component is not to be checked by a write check.

Abbreviation: NWCK