IDCAMS ALTER

The IDCAMS ALTER command lets you change attributes of an existing VSAM cluster, alternate index, or path without deleting the object and redefining it. That avoids the usual cycle of backing up data, deleting the file, defining a new one with different parameters, and restoring the data. You can change free space, record size, share options, volumes, retention, and other parameters. Some attributes—such as key definition and control interval size—cannot be changed with ALTER; they are fixed at define time. This page explains what you can and cannot alter, the ALTER syntax, common parameters (FREESPACE, RECORDSIZE, SHAREOPTIONS, ADDVOLUMES, NEWNAME), and when you must delete and recreate instead.

What ALTER Does

ALTER updates catalog information and possibly allocation for an existing VSAM object. The object (cluster, AIX, or path) stays in place; only the attributes you specify are changed. For example, if the cluster is running out of free space and you are getting frequent splits, you can ALTER to increase FREESPACE. The increase applies to new control intervals and control areas that are allocated from then on; existing CIs and CAs keep their current free space. So ALTER is for tuning and adjusting, not for changing fundamental structure like keys or CI size.

General Syntax

The ALTER command takes an entry name (cluster name, AIX name, or path name) and one or more parameters to change. Basic form:

1
2
3
4
5
6
7
8
9
10
11
12
  ALTER entry-name -
    [ FREESPACE(ci-percent ca-percent) ] -
    [ RECORDSIZE(average maximum) ] -
    [ SHAREOPTIONS(crossregion crosssystem) ] -
    [ ADDVOLUMES(volser [ volser ... ]) ] -
    [ REMOVEVOLUMES(volser [ volser ... ]) ] -
    [ NEWNAME(newname) ] -
    [ ERASE | NOERASE ] -
    [ TO(date) | FOR(days) ] -
    [ BUFFERSPACE(size) ] -
  [ CATALOG(catname) ]
 

entry-name is the name of the cluster, AIX, path, or component (e.g. cluster.DATA). You specify only the parameters you want to change. The rest stay as they were. For a path or AIX, you can use parameters such as UPDATE/NOUPDATE or UPGRADE/NOUPGRADE (path and AIX) in addition to the ones above. CATALOG(catname) specifies the catalog where the entry lives; omit to use the default catalog.

What You Can Alter

The following table lists common attributes you can change with ALTER. Exact support depends on your IDCAMS version and the object type (cluster, AIX, path).

What You Cannot Alter

Some attributes are fixed at define time and cannot be changed with ALTER. To change them you must define a new cluster (or AIX) with the desired attributes and copy the data (e.g. with REPRO), then delete the old object and optionally rename the new one.

FREESPACE

FREESPACE(ci-percent ca-percent) sets the free space percentage for new control intervals and new control areas. Existing CIs and CAs keep the free space they had when they were created. So if you started with FREESPACE(10 5) and later ALTER to FREESPACE(20 10), only CIs and CAs allocated after the ALTER will have 20% and 10% free space. Increasing free space can reduce how often splits occur when you insert records. You cannot reduce the physical free space already in existing CIs; you can only change the rule for future allocation.

RECORDSIZE

RECORDSIZE(average maximum) changes the record size limits. The new maximum must be at least as large as the largest record currently in the file. If you have variable-length records and your application starts writing longer records, you can ALTER to increase the maximum. You cannot reduce the maximum below the size of an existing record. The average is used for space calculations; changing it does not change existing data, only how much space is reserved for new records in some cases.

SHAREOPTIONS

SHAREOPTIONS(crossregion crosssystem) controls how the cluster can be shared. The first number (crossregion) applies when multiple address spaces in the same system access the file; the second (crosssystem) applies when multiple systems (e.g. in a sysplex) access it. Values typically range from 1 to 4 with different meanings for read-only vs update and for when the file can be shared. Use ALTER to relax or tighten sharing when your usage pattern changes. The new values take effect the next time the file is opened.

ADDVOLUMES and REMOVEVOLUMES

ADDVOLUMES(volser ...) adds one or more volumes to the cluster. The cluster can then use more DASD. On many systems the cluster should be closed when you run ALTER ADDVOLUMES; consult your documentation. REMOVEVOLUMES(volser ...) removes volumes. The volumes must be empty of data for that cluster, or you must have moved the data. Use REMOVEVOLUMES with care to avoid data loss.

NEWNAME (Renaming)

NEWNAME(newname) renames the catalog entry. After the ALTER, the object is known by the new name. All JCL and programs that reference the cluster (or path, or AIX) must use the new name. To rename the cluster and its components (DATA, INDEX), use a generic name and NEWNAME with a generic: for example ALTER cluster.name.* NEWNAME(new.name.*). That renames the cluster and all component entries so that the data and index component names follow the new naming pattern. Renaming does not move or copy data; it only changes the name in the catalog.

ALTER for Paths and AIX

For a path you can use ALTER to change UPDATE/NOUPDATE (whether the AIX is opened for update when the base is updated). For an alternate index you can change UPGRADE/NOUPGRADE (whether the AIX is automatically maintained when the base cluster changes). Other path- or AIX-specific parameters may be alterable depending on your system. The syntax is the same: ALTER path-name or aix-name followed by the parameters to change.

When Changes Take Effect

Most ALTER changes are stored in the catalog immediately but apply to the object the next time it is opened. If the cluster is open (e.g. by a batch job or CICS region), close it and reopen it for the new attributes to take effect. For ADDVOLUMES and REMOVEVOLUMES, the cluster is often required to be closed when you run ALTER; otherwise the change may be deferred or rejected.

Example: Increase Free Space

1
2
3
  ALTER MY.FILE.KSDS -
    FREESPACE(20 10)
 

New control intervals will have 20% free space and new control areas 10%. Existing CIs and CAs are unchanged. Use this when you are seeing many splits and want more room for inserts.

Example: Rename a Cluster

1
2
3
4
5
  ALTER MY.OLD.NAME.KSDS -
    NEWNAME(MY.NEW.NAME.KSDS)
  ALTER MY.OLD.NAME.KSDS.* -
    NEWNAME(MY.NEW.NAME.KSDS.*)
 

The first ALTER renames the cluster entry. The second renames the component entries (e.g. MY.OLD.NAME.KSDS.DATA to MY.NEW.NAME.KSDS.DATA). After this, use MY.NEW.NAME.KSDS in JCL and in programs.

Example: Add a Volume

1
2
3
  ALTER MY.FILE.KSDS -
    ADDVOLUMES(MYVOL2)
 

Adds MYVOL2 to the list of volumes for the cluster. The cluster should be closed. After the ALTER, the system can allocate new extents on MYVOL2 when the cluster grows.

Key Takeaways

• ALTER changes attributes of an existing VSAM object without delete and redefine. You specify the entry name and the parameters to change.
• You can alter FREESPACE, RECORDSIZE, SHAREOPTIONS, ADDVOLUMES, REMOVEVOLUMES, NEWNAME, ERASE/NOERASE, TO/FOR, and BUFFERSPACE, among others.
• You cannot alter KEYS, CISZ, or dataset organization (e.g. convert KSDS to ESDS). For those, define a new cluster and REPRO the data.
• FREESPACE and RECORDSIZE changes apply to new CIs/CAs or to catalog metadata; existing allocated space may be unchanged.
• ALTER changes take effect the next time the object is opened. Close the object before ALTER when required (e.g. for ADDVOLUMES).

Explain Like I'm Five

Imagine you have a filing cabinet (the cluster). ALTER is like changing the rules for the cabinet without buying a new one: you can say "from now on, leave more empty space in each drawer" (FREESPACE), or "this cabinet can now be used by two people at once" (SHAREOPTIONS), or "we are going to call this cabinet the Red Cabinet instead of the Blue Cabinet" (NEWNAME). But you cannot turn it into a different kind of cabinet (e.g. one with a different key system) with ALTER; for that you need a new cabinet and you move the folders (REPRO).

Test Your Knowledge