Optional Parameters
- BUFFERSPACE(size|3072)
- Provides
the amount of space for buffers. The size you specify for the buffer
space helps VSAM determine the size of the data component's and index
component's control interval. If BUFFERSPACE is not coded, VSAM attempts
to get enough space to contain two data set control intervals and,
if the data set is key-sequenced, one index control interval.
The size specified cannot be less than enough space to contain two data component control intervals. If the data is key-sequenced, it should contain only one index control interval. If the specified size is less than VSAM requires for the buffers needed to run your job, the default BUFFERSPACE calculation overrides the size.
This is the default BUFFERSPACE calculation: Data control interval size x 2 + index control interval size.- size
- Provides the amount of space, in bytes, for buffers.
Size can be expressed in decimal (n), hexadecimal (X'n'),
or binary (B'n') form. 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.
Abbreviation: BUFSP or BUFSPC
- BUFND(number)
- Specifies
the number of I/O buffers VSAM is to use for transmitting data between
virtual and auxiliary storage.
The size of the buffer is the size of the data component control interval. The minimum number you can specify is the number specified for STRNO plus 1.
Note that minimum buffer specification does not provide optimum sequential processing performance. Additional data buffers benefit direct inserts or updates during control area splits and will also benefit spanned record accessing.- number
The number of data buffers to be used. The minimum
number allowed is 3; the maximum number allowed is 32767.
Abbreviation: BFND
- BUFNI(number)
- Specifies
the number of I/O buffers VSAM is to use for transmitting the contents
of index entries between virtual and auxiliary storage for keyed access.
The size of the buffer is the size of the index control interval. The minimum number you can specify is the number specified for STRNO.
Additional index buffers will improve performance by providing for the residency of some or all the high-level index (index set records), thereby minimizing the number of high-level index records to be retrieved from DASD for key-direct processing.- number
- The number of index buffers to be used. The minimum
number allowed is 3 and the maximum number allowed is 32767.
Abbreviation: BFNI
- CATALOG(mastercatname)
- Unused
parameter. Retained for compatibility only.
- mastercatname
- Regardless of specification, the entry will go into the current system master catalog.
Abbreviation: CAT
- CONTROLINTERVALSIZE(size)
- Specifies
the size of the control interval for the catalog or component.
The size of the control interval depends on the maximum size of the data records and the amount of buffer space you provide.
If you do not code the CONTROLINTERVALSIZE, VSAM determines the size of control intervals. If you have not specified BUFFERSPACE and the size of your records permits, VSAM calculates the optimum control interval size for the data and index components. This is based partly on device characteristics.If the control interval size calculated by VSAM as required for the index component is greater than the value specified in the parameter, the value calculated by VSAM will be used.- size
- The size of the data and index components of a catalog.
The maximum control interval size is 32 768 bytes.
You can specify a size from 512 to 8K in increments of 512 or from 8K to 32K in increments of 2K. K is 1024 in decimal notation. If you select a size that is not a multiple of 512 or 2048, VSAM chooses the next higher multiple.
Refer to z/OS DFSMS Using Data Sets for a discussion of the relationship between control interval size and physical block size. The discussion also includes restrictions that apply to control interval size and physical block size.
Abbreviation: CISZ or CNVSZ
- DATACLASS(class)
- Specifies
the name, 1-to-8 characters, of the data class. DATACLASS can be specified
for SMS-managed and non-SMS-managed data sets. 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 specifying other attributes. See Understanding the Order of Assigned Data Set Attributes for the order of precedence (filtering)
the system uses to select the attributes to assign.
The record organization attribute of DATACLASS is not used by DEFINE USERCATALOG/MASTERCATALOG. If DATACLASS is specified and SMS is inactive, DEFINE will be unsuccessful. DATACLASS cannot be specified as a subparameter of DATA or INDEX.
Abbreviation: DATACLAS
- EATTR(NO | OPT)
- Specifies whether a catalog can have extended attributes (format
8 and 9 DSCBs) and optionally reside in EAS. The system records the
value for EATTR in the VVDS for the catalog objects and in the DSCBs
created in the VTOC.
- NO
- The catalog can not have extended attributes (format 8 and 9 DSCBs) or optionally reside in EAS. The catalog is restricted to track-managed space. NO is the default.
- OPT
- The catalog can optionally have extended attributes (format 8 and 9 DSCBs) and can optionally reside in EAS.
- ECSHARING|NOECSHARING
- Indicate whether or not sharing the catalog can be performed via
the coupling facility.
- ECSHARING
- Enhanced
Catalog Sharing (ECS) is allowed. ECS is a catalog sharing method
that makes use of a coupling facility to improve 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 will be performed, but
the ECS sharing method will not be used.
Abbreviation: NOECSHR
- FILE(ddname)
- Specifies the name of the DD statement that identifies the device and volume to be used for the catalog. The DD statement should specify DISP=OLD to prevent premature space allocation on the volume. If FILE is not specified and the catalog's volume is physically mounted, the volume identified with the VOLUME parameter is dynamically allocated. The volume must be mounted as permanently resident or reserved.
- FREESPACE(CI_percent[ CA_percent]|0 0)
- Specifies
the amount of space that is to be left free when the catalog is loaded
and after any split of control intervals (CI_percent)
and control areas (CA_percent).
The empty space in the control interval and control area is available for data records that are updated and inserted after the catalog is initially loaded.
The amounts are specified as percentages. C_percent translates into a number of bytes that is equal to, or slightly less than, the percentage value of CI_percent. CA_percent translates into a number of control intervals that is equal to, or less than, the percentage value of CA_percent.
CI_percent and CA_percent, must be equal to or less than 100. If you use FREESPACE(100 100), one data record is placed in each control interval used for data and 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).
When no FREESPACE value is coded, the default specifies that no free space is to be reserved when the data set is loaded.
Abbreviation: FSPC
- [ICFCATALOG|VOLCATALOG]
- Specify the type of catalog to be defined.
- ICFCATALOG
- Defines
a catalog.
Abbreviation: ICFCAT
- VOLCATALOG
- Defines
a tape volume catalog (VOLCAT). A VOLCAT can contain only tape library
and tape volume entries. You can define either a general VOLCAT or
a specific VOLCAT.
- A
general VOLCAT is the default tape volume catalog. A general VOLCAT
contains all tape library entries and any tape volume entries that
do not point to a specific VOLCAT. Each system can have access to
only one general VOLCAT. You must define the general VOLCAT prior
to bringing the tape libraries online. The general VOLCAT must be in the form:
- XXXXXXXX.VOLCAT.VGENERAL
where XXXXXXXX either defaults to SYS1 or to another high level qualifier specified by the LOADxx member in SYS1.PARMLIB. For more information on changing the high-level qualifier for VOLCATs, see the section on bypassing SYSCATxx with LOADxx in z/OS DFSMS Managing Catalogs.
- A specific VOLCAT is a tape volume catalog that contains a specific group
of tape volume entries based on the tape volume serial numbers (tape
volsers). A specific VOLCAT cannot contain tape library entries. The specific VOLCAT must be in the form:
- XXXXXXXX.VOLCAT.Vy
- where XXXXXXXX either defaults to SYS1 or is another high-level qualifier specified by the LOADxx member in SYS1.PARMLIB.
- where y represents the first character of a tape volser. A specific VOLCAT contains all the tape volume entries with volsers whose first character is equal to y. See Tape Volume Names for a discussion of the naming restrictions for tape volume volsers.
Abbreviation: VOLCAT
- A
general VOLCAT is the default tape volume catalog. A general VOLCAT
contains all tape library entries and any tape volume entries that
do not point to a specific VOLCAT. Each system can have access to
only one general VOLCAT. You must define the general VOLCAT prior
to bringing the tape libraries online.
- IMBED|NOIMBED
- IMBED|NOIMBED is no longer supported; if it is specified, it will be ignored and no message will be issued.
- {[LOCK|UNLOCK] | [SUSPEND|RESUME]}
- You can specify either
LOCK|UNLOCK or SUSPEND|RESUME, these parameters are mutually exclusive.
- LOCK|UNLOCK
- Controls the setting of the catalog lock attribute, and therefore
checks access to a catalog. LOCK and UNLOCK can be specified only
when the entryname identifies a catalog. UNLOCK is the default. Before
you lock a catalog, review the information on locking catalogs in z/OS DFSMS Managing Catalogs.
- LOCK
- Specifies that the catalog identified by entryname is to be defined with the lock attribute on. Defining the catalog with the lock on restricts catalog access to authorized personnel. Specification of this parameter requires read authority to the profile name, IGG.CATLOCK, with class type FACILITY. Catalogs are usually defined with the lock attribute on only after a DELETE RECOVERY during catalog recovery operations. 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).
- UNLOCK
- Specifies that the catalog identified by entry name is to be defined with the lock attribute off. UNLOCK is the default.
- SUSPEND|RESUME
- Specifies whether catalog requests are suspended or resumed following
the catalog define.
- SUSPEND
- Specifies that requests for this catalog be suspended until a RESUME is issued via theF CATALOG,RECOVER,RESUME or ALTER RESUME command is issued.
- RESUME
- Specifies that requests for this catalog execute immediately. RESUME is the default.
- LOG(NONE)
-
- NONE
- Specifies that the catalog is eligible to be accessed with VSAM
record-level sharing (RLS) as a non-recoverable catalog.
If you specify LOG on the SMS data class, that value is used as the data set definition, unless you previously defined it with an explicitly specified or modeled DEFINE attribute.
- RLSQUIESE|RLSENABLE
- Specifies whether the catalog will be accessed with non-record-level
sharing (NSR) or record-level sharing (RLS) access on first
reference. You can only specify RLSQUIESE|RLSENABLE
parameters along with the LOG(NONE) parameter.
- RLSQUIESCE
- The catalog will be accessed with NSR following the define of
the catalog. This is the default value.
Abbreviation: RLSQ
- RLSENABLE
- The cluster will be accessed with RLS following the define of
the catalog.
Abbreviation: RLSE
- MANAGEMENTCLASS(class)
- For
SMS-managed data sets: Specifies the name, 1-to-8 characters,
of the management class. Your storage administrator defines the names
of the management classes you can specify. If MANAGEMENTCLASS is not
specified, but STORAGECLASS is specified or defaulted, MANAGEMENTCLASS
is derived from automatic class selection (ACS). If MANAGEMENTCLASS
is specified and SMS is inactive, DEFINE will be unsuccessful. MANAGEMENTCLASS
cannot be specified as a subparameter of DATA or INDEX.
Abbreviation: MGMTCLAS
- MODEL(entryname[ catname])
- Specifies
that an existing master or user catalog is to be used as a model for
the user catalog being defined.
When one entry is used as a model for another, its attributes are copied as the new entry is defined. You can use some attributes of the model and override others by explicitly specifying them in the definition of the user catalog.
If a model is used, you must specify certain parameters even though no attributes are to be changed or added. The name of the user catalog to be defined and volume and space information must always be specified as parameters of USERCATALOG. See Understanding the Order of Assigned Data Set Attributes for information about the order in which the system selects an attribute.
STORAGECLASS and MANAGEMENTCLASS classes can be modeled. If DATACLASS exists for the entry being used as a model, it is ignored.- entryname
- Specifies the name of the master or user catalog to be used as a model.
You can specify the EATTR parameter with MODEL.
- OWNER(ownerid)
- Specifies the identification of the owner of the catalog being defined.
- RECONNECT
- Specifies that the catalog being defined use existing alias information.
- RECORDSIZE(average maximum|4086 32400) Abbreviation: RECSZ
- If you specify record size it is ignored, and no error message gets issued.
- REPLICATE|NOREPLICATE
- REPLICATE|NOREPLICATE is no longer supported; if it is specified, it will be ignored and no message will be issued.
- SHAREOPTIONS(crossregion[ crosssystem]|3 4) Abbreviation: SHR
- Specifies
how a catalog can be shared among users. This
specification applies to both the data and index components of the
catalog.
- 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
the catalog concurrently.
- 1
- Reserved
- 2
- Reserved
- 3
- Specifies that the catalog can be fully shared by any number of users. With this option, each user opening the catalog as a data set is responsible for maintaining both read and write integrity for the data the program accesses. User programs that ignore the write integrity guidelines can cause VSAM program checks, lost or inaccessible records, uncorrectable catalog errors, and other unpredictable results. This option places heavy responsibility on each user sharing the catalog.
- 4
- Reserved
- crosssystem
- Specifies
the amount of sharing allowed among systems. Job steps of two or more
operating systems can gain access to the same catalog. To get exclusive
control of the catalog'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. You can use:
- 1
- Reserved
- 2
- Reserved
- 3
- Specifies that the catalog is not being shared across systems. SHAREOPTIONS(3 3) would direct the catalog open process to unconditionally bypass the setting of the buffer invalidation indicator. Hence, even though the catalog resided on a shared DASD device, buffer invalidation would not occur. This performance option must be selected only when the user can guarantee that the catalog is not being shared across multiple processors.
- 4
- Specifies that the catalog can be fully shared. The integrity of the buffers and control block structure is maintained by catalog management.
- STORAGECLASS(class) Abbreviation: STORCLAS
- For
SMS-managed data sets: Specifies the 1-to-8 character name of
the storage class. Your storage administrator defines the names of
the storage classes you can specify. Use the storage class to specify
the storage service level to be used by SMS for storage of the catalog.
If STORAGECLASS is specified and SMS is inactive, DEFINE will be unsuccessful.
STORAGECLASS cannot be specified as a subparameter of DATA or INDEX.
- STRNO(number|2)
- Specifies
the number of requests (RPLs) requiring concurrent data set positioning
that VSAM is to be prepared to accommodate.
- number
- The number of requests catalog administration must be prepared to accommodate. The minimum number allowed is 2 and the maximum number is 255.
- TO(date)|FOR(days)
- Specifies
the retention period for the catalog being defined. If no value is
coded, the catalog can be deleted whenever it is empty.
The MANAGEMENTCLASS maximum retention period, if specified, limits the retention period specified by this parameter.
For non-SMS-managed catalogs, the correct retention period is reflected in the catalog entry. The VTOC entry cannot contain the correct retention period. Enter a LISTCAT command to see the correct expiration date.
For SMS-managed catalogs, the expiration date in the catalog is updated and the expiration date in the format-1 DSCB is changed. Should the expiration date in the catalog not agree with the expiration date in the VTOC, the VTOC entry overrides the catalog entry. In this case, enter a LISTVTOC command to see the correct expiration date.- TO(date)
- Specifies
the earliest date that a command without the PURGE parameter can delete
the catalog. 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 the catalog. 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 the catalog immediately eligible for deletion.
- FOR(days)
- Specifies the number of days to keep the catalog. 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.
- WRITECHECK|NOWRITECHECK
- Specify whether or not the catalog is to be checked by a direct
access device operation called write check when a record is written
to the device.
- WRITECHECK Abbreviation: WCK
- Specifies that a record is to be written and then read, without data transfer.
- NOWRITECHECK Abbreviation: NWCK
- Specifies that the catalog is not to be checked by a write Checks to see if a record has been written to the device.