|
The DEFINE ALTERNATEINDEX command has the following optional parameters.
- BUFFERSPACE(size)
- Provides
the minimum space for buffers. VSAM determines the data component's
and index component's control interval size. If you do not use BUFFERSPACE,
VSAM provides enough space to contain two data component control intervals
and, if the data is key-sequenced, one index component control interval.
- size
- is the buffer of space. You can use decimal (n),
hexadecimal (X'n'), or binary (B'n'). 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 the
buffer size is less than VSAM requires to run your job, it will be
treated as though the parameter was not specified and the buffer size
will be set to the default value.
Exception: When you
use RLS or DFSMStvs access, DFSMS ignores BUFFERSPACE.
Note: The
limitations of the bufferspace value on how many buffers will be allocated
is based on storage available in your region, and other parameters
or attributes of the data set.
Abbreviations: BUFSP or BUFSPC
- CATALOG(catname)
- Identifies
the catalog in which the alternate index is defined. The catalog also
contains the base cluster's entry (see the description of the RELATE
in preceding text). See Catalog Selection Order for DEFINE for the
order in which a catalog is selected if the catalog's name is not
specified.
Before you can assign catalog names for SMS-managed
data sets, you must have access to the RACF® STGADMIN.IGG.DIRCAT
FACILITY class. See Storage Management Subsystem (SMS) Considerations for more
information. - catname/alias
- Names the catalog or an alias that can be resolved
to a catalog. For example, if alias ABCD relates to catalog SYS1.USERCAT
then specifying either ABCD or SYS1.USERCAT will cause the alternate
index to be defined in SYS1.USERCAT.
Abbreviation: CAT
If the catalog's volume is physically mounted, it is
dynamically allocated. Mount the volume as permanently resident or
reserved.
If the catalog's volume is physically mounted,
it is dynamically allocated. Mount the volume as permanently resident
or reserved.
- CONTROLINTERVALSIZE(size)
- Defines
the size of the alternate index's control intervals. This depends
on the maximum size of data records, and on the amount of buffer space
given.
LSR/GSR buffering technique users can ensure buffer pool
selection by explicitly defining data and index control interval sizes.
When
you do not specify the control interval size, VSAM determines the
control interval size. If you have not specified BUFFERSPACE and the
size of your records permits, VSAM selects the optimum size for the
data control interval size and 512 bytes for the index control interval
size. - size
- The size of the alternate index's data and index components.
Because
an alternate index always has the spanned attribute, the control interval
size can be less than the maximum record length. You can define a
size from 512, to 8K in increments of 512 or from 8K to 32K in increments
of 2K (where K is 1024 in decimal notation). If you use a size that
is not a multiple of 512 or 2048, VSAM chooses the next higher multiple.
The
index control interval should be large enough to accommodate all of
the compressed keys in a data control area. If the index control interval
size is too small, unnecessary control area splits can occur. After
the first define (DEFINE), a catalog listing ( LISTC ) shows the number
of control intervals in a control area and the key length of the data
set. To make a general estimate of the index control interval size
needed, multiply one-half of the key length (KEYLEN) by the number
of data control intervals per control area (DATA CI/CA):
(KEYLEN/2
) * DATA CI/CA ≤ INDEX CISIZE
For information about the relationship
between control interval size and physical block size, see z/OS DFSMS Using Data Sets
for the relationship between control interval size and physical block
size. This document also includes restrictions that apply to control
interval size and physical block size.
Abbreviations: CISZ or CNVSZ
- DATACLASS(class)
- The
1 to 8 character name of the data class for the data set. The DATACLASS
parameter 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 defining other
attributes. See Understanding the Order of Assigned Data Set Attributes for the order
of precedence (filtering) the system uses to select which attribute
to assign. The record organization attribute of DATACLASS is not used
for DEFINE ALTERNATEINDEX.
DATACLASS parameters apply to both
SMS-managed and non-SMS-managed data sets. If DATACLASS is used and
SMS is inactive, the DEFINE is unsuccessful.
You cannot use
DATACLASS as a subparameter of DATA or INDEX.
Abbreviation:
DATACLAS
- ERASE|NOERASE
- indicates if the records of the alternate index components are
erased when the alternate index is deleted.
- ERASE
- Requires
the records of the alternate index components are overwritten with
binary zeros when the alternate index is deleted. If the base cluster
of the alternate index is protected by a RACF generic or discrete profile and the base
cluster is cataloged in a catalog, you can use RACF commands to specify an ERASE attribute
as part of this profile so that the component is automatically erased
upon deletion.
Abbreviation: ERAS
- NOERASE
- Specifies
that the records of the alternate index components are not to be overwritten
with binary zeros. NOERASE prevents the component from being erased
if the base cluster of the alternate index is protected by a RACF generic or discrete profile
that specifies the ERASE attribute and if the base cluster is cataloged
in a catalog. You can use RACF commands
to alter the ERASE attribute in a profile.
Abbreviation:
NERAS
- EXCEPTIONEXIT(entrypoint)
- The
name of your 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 alternate index's direct
access storage space. (An exception is any condition that causes a
SYNAD exit to be taken.) The component's exception exit routine is
processed first; then 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.
Abbreviation:
EEXT
- FILE(ddname)
- Names
the DD statement that identifies the direct access devices and volumes
on which to allocate space to the alternate index. If more than one
volume is specified in a volume list, all volumes must be the same
device type.
When the data component and index component are to
reside on different devices, you can create a separate FILE parameter
as a parameter of DATA and INDEX to point to different DD statements.
If
the FILE parameter is not used, an attempt is made to dynamically
allocate the required volumes. The volumes must be mounted as permanently
resident or reserved.
The DD statement you specify must be:
//ddname DD UNIT=(devtype[,unitcount]),
// VOL=SER=(volser1,volser2,volser3,...),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[
CA-percent]|0 0)
- Designates
the amount of empty space left after any primary or secondary allocation
and any split of control intervals (CI-percent) and
control areas (CA-percent) when the alternate
index is built (see BLDINDEX). The empty
space in the control interval and control area is available for data
records that are updated and inserted after the alternate index is
initially built. The amounts are specified as percentages. CI-percent translates
into a number of bytes that is either equal to, or slightly less than,
the percentage value of CI-percent. CA-percent translates
into a number of control intervals that is either equal to, or less
than, the percentage of CA-percent.
The
percentages must be equal to, or less than, 100. When you use 100%
of free space, one data record is placed in the first control interval
of each control area when the alternate index is built.
Abbreviation:
FSPC
- IMBED|NOIMBED
- IMBED|NOIMBED is no longer supported; if it is specified, VSAM
ignores it, and no message is issued.
- KEYRANGES((lowkey highkey)[(lowkey highkey)...])
- KEYRANGE is no longer supported; If you specify this parameter,
VSAM ignores it, and no message is issued.
- KEYS(length offset|64 0)
- Describes
the alternate-key field in the base cluster's data record.
The
key field of an alternate index is called an alternate key. The data
record's alternate key can overlap or be contained entirely within
another (alternate or prime) key field.
The length plus offset
cannot be greater than the length of the base cluster's data record.
When
the base cluster's data record spans control intervals, the record's
alternate-key field is within the record's first segment (that is,
in the first control interval). - length offset
- Gives the length of the alternate key, in
bytes, and its displacement from the beginning of the base cluster's
data record, in bytes.
- MODEL(entryname[
catname])
- Uses
existing entry as a model for the entry being defined or re-cataloged.
DATACLASS, MANAGEMENTCLASS, and STORAGECLASS cannot be modeled.
See Understanding the Order of Assigned Data Set Attributes for information on how
the system selects modeled attributes.
You can use an existing
alternate index's entry as a model for the attributes of the alternate
index 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 defining
them in the cluster or component. If you do not want to add or change
any attributes, use only the entry type of the model (alternate index,
data, or index) and the name of the entry to be defined.
When
you use an alternate index entry as a model for an alternate index,
the model entry's data and index components are used as models for
the to-be-defined entry's data and index components, unless another
entry is specified with the MODEL parameter as a subparameter of DATA
or INDEX. - entryname
- Names the entry to be used as a model.
- catname
- Names the model entry's catalog. You must identify the catalog
that contains the model entry when you want to assign the catalog's
password instead of the model entry's password.
If the catalog's
volume is physically mounted, it is dynamically allocated. The volume
must be mounted as permanently resident or reserved. See Catalog Selection Order for DEFINE for information about the order in which
a catalog is selected when the catalog's name is not specified.
- ORDERED|UNORDERED
- ORDERED|UNORDERED is no longer supported; if it is specified,
it will be ignored and no message will be issued.
- OWNER(ownerid)
- Gives
the identification of the alternate index's owner.
For TSO/E users,
if the OWNER parameter does not identify the owner, the TSO/E user's
userid becomes the ownerid value.
- RECATALOG|NORECATALOG
- Specifies whether the catalog entries for the alternate index
components are re-created from information in the VVDS.
- RECATALOG
- Recreates
the catalog entries if valid VVDS entries are found on the primary
VVDS volume. If not, the command ends.
Use of RECATALOG requires
that the NAME, RELATE, and VOLUMES parameters be specified as they
were when the alternate index was originally defined. If you use RECATALOG,
you are not required to include CYLINDERS, RECORDS, or TRACKS.
If
ATTEMPTS, AUTHORIZATION, CATALOG, CODE, MODEL, NOUPGRADE, or OWNER
parameters were used during the original define, they must be entered
again with RECATALOG to restore their original values; otherwise,
their default values are used.
Abbreviation: RCTLG
- NORECATALOG
- Specifies
that the catalog entries are not to be re-created from VVDS entries.
Catalog entries are created for the first time.
Abbreviation:
NRCTLG
- RECORDSIZE(average maximum|4086 32600)
- The average and maximum length,
in bytes, of an alternate index record.
An alternate index record
can span control intervals, so RECORDSIZE can be larger than CONTROLINTERVALSIZE. The formula
for the maximum record size of spanned records as calculated by VSAM
is: 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
You can use either of the following formulas to determine
the size of the alternate index record:
Variables in the formulas represent these values: - RECSZ is the average record size.
- AIXKL is the alternate-key length (see the KEYS parameter).
- BCKL is the base cluster's prime-key length. (You can enter the
LISTCAT command to determine this base cluster's prime-key length).
- n = 1 when UNIQUEKEY is specified (RECSZ is also the maximum record
size).
- n = the number of data records in the base cluster that contain
the same alternate-key value, when NONUNIQUEKEY is specified.
When you use NONUNIQUEKEY, give a record size large enough
to allow for as many key pointers or RBA pointers as you might need.
The record length values apply only to the alternate index's data
component.
Restriction: REPRO
to non-VSAM targets and EXPORT do not support data sets with record
sizes greater than 32760. The maximum number of prime keys that a
single alternate index logical record can contain is 32767.
- REPLICATE|NOREPLICATE
- The REPLICATE|NOREPLICATE parameter is no longer supported. If
you specify this parameter, VSAM ignores it, and no message is issued.
- REUSE|NOREUSE
- Indicates whether or not the alternate index can be used again
as a new alternate index.
- REUSE
- Indicates
that the alternate index can be used over again as a new alternate
index. When a reusable alternate index is opened, its high-used RBA
can be set to zero. Open it with an access control block using the
RESET attribute.
When you use BLDINDEX to build a reusable alternate
index, the high-used RBA is always reset to zero when the alternate
index is opened for BLDINDEX processing.
Reusable alternate
indexes can be multivolumed and might have up to 123 physical extents.
Exception: If
you use the keyword UNIQUE with REUSE, the DEFINE command is unsuccessful.
Abbreviation:
RUS
- NOREUSE
- Specifies
that the alternate index cannot be used again as a new alternate index.
Abbreviation: NRUS
- SHAREOPTIONS(crossregion[
crosssystem]|1 3)
- Specifies how an alternate
index's data or index component 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 data integrity, ensure
that share options defined for data and index components are the same.
For a description of data set sharing, see z/OS DFSMS Using Data Sets.
- crossregion
- Indicates
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 include 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. This setting does not allow any non-RLS access when the
data set is already open for VSAM RLS or DFSMStvs processing. An
RLS or DFSMStvs open fails 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 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 specified 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 are: - 1
- Reserved.
- 2
- Reserved.
- 3
- Specifies that the data set can be fully shared. 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 result in:
- VSAM program checks
- Uncorrectable data set errors
- Unpredictable results
The RESERVE and DEQ macros are required with this option to
maintain data set integrity. (See z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN and z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU
for information on using RESERVE and DEQ.) If the sphere is accessed
using VSAM RLS or DFSMStvs protocols, VSAM RLS maintains the required
integrity.
- 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. (See z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN and z/OS MVS Programming: Authorized Assembler Services Reference LLA-SDU for information on using RESERVE and
DEQ.) 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 used.
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 writes the appropriate buffer immediately into the VSAM
object's DASD. VSAM writes out the buffer in the user's address space
that contains the new or updated data record.
- Each GET refreshes the user's input buffers. The contents of each
data and index buffer used by the user's program is retrieved from
the VSAM object's DASD.
Exception: If you use VSAM RLS or DFSMStvs,
SHAREOPTIONS is assumed to be (3,3). If you do not use VSAM RLS or
DFSMStvs, the SHAREOPTIONS specification is respected.
Abbreviation:
SHR
- SPEED|RECOVERY
- Specifies whether the data component's control areas are to be
preformatted during loading.
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, regardless of which option is used.
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
control intervals. These preformatted control intervals are then updated,
using update writes with the data records. When SPEED is used, the
initial load is faster. - SPEED
- Does
not preformat the data component's space.
If the initial load
is unsuccessful, you must load the data set 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 data records.
- RECOVERY
- Does
preformat the data component's space prior to writing the data records.
If the initial load is unsuccessful, VSAM can determine the location
of the last record written during the load process.
Abbreviation:
RCVY
- TO(date)|FOR(days)
- The
retention period for the alternate index. The alternate index is not
automatically deleted when the expiration date is reached. When you
do not provide a retention period, the alternate index can be deleted
at any time. The MANAGEMENTCLASS maximum retention period, if used,
limits the retention period named by this parameter.
For non-SMS-managed
data sets, the correct retention period is reflected in the catalog
entry. The VTOC entry might not have the correct retention period.
Enter a LISTCAT command to see 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. 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 alternate index. 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 alternate index. 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 alternate index immediately eligible for deletion.
- FOR(days)
- Is
the number of days to keep the alternate index before it is deleted.
The maximum number is 9999. If the number is 0 through 9998, the alternate
index is retained for that number of days; if the number is 9999,
the alternate index is retained indefinitely.
- UNIQUEKEY|NONUNIQUEKEY
- Shows whether
more than one data record (in the base cluster) can contain the same
key value for the alternate index.
- UNIQUEKEY
- Points
each alternate index key to only one data record. When the alternate
index is built (see BLDINDEX) and more
than one data record contains the same key value for the alternate
index, the BLDINDEX processing ends with an error message.
Abbreviation:
UNQK
- NONUNIQUEKEY
- points
a key value for the alternate index to more than one data record in
the base cluster. The alternate index's key record points to a maximum
of 32768 records with non-unique keys.
When you include NONUNIQUEKEY,
the maximum record size should be large enough to allow for alternate
index records that point to more than one data record.
Abbreviations:
NUNQK
- UPGRADE|NOUPGRADE
- Specifies whether or not the alternate index is to be upgraded
(that is, kept up to date) when its base cluster is modified.
- UPGRADE
- Upgrades
the cluster's alternate index to reflect changed data when the base
cluster's records are added to, updated, or erased.
When UPGRADE
is specified, the alternate index's name is cataloged with the names
of other alternate indexes for the base cluster. The group of alternate
index names identifies the upgrade set that includes all the base
cluster's alternate indexes that are opened when the base cluster
is opened for write operations.
The UPGRADE attribute is not
effective for the alternate index until the alternate index is built
(see BLDINDEX). If the alternate index
is defined when the base cluster is open, the UPGRADE attribute takes
effect the next time the base cluster is opened.
Abbreviation:
UPG
- NOUPGRADE
- Specifies
that the alternate index does not upgrade when its base cluster is
modified.
Abbreviation: NUPG
- WRITECHECK|NOWRITECHECK
- Determines
whether an alternate index or component is checked by a machine action
called write-check when a record is written into it.
- WRITECHECK
- Indicates that a record is written and then read, without data
transfer, to test for the data check condition.
Exception:When
you use VSAM RLS or DFSMStvs access, the WRITECHECK parameter is ignored.
Abbreviation:
WCK
- NOWRITECHECK
- Does not write-check the alternate index or component checked
by a write check.
Abbreviation: NWCK
|