IDCAMS RENAME (ALTER NEWNAME)

On the mainframe you rename a VSAM cluster, path, or alternate index using the IDCAMS ALTER command with the NEWNAME parameter. There is no separate RENAME command; ALTER entry-name NEWNAME(new-name) changes the catalog entry so the object is known by the new name. After the rename, all applications and JCL must use the new name. The dataset must not be in use when you run the rename. This page explains the syntax for renaming clusters, paths, and AIXs, how to rename a cluster and its components together with NEWNAME(newname.*), and important restrictions (dataset not open, SMS, catalog access). It also briefly mentions alternatives such as defining a new cluster and using REPRO when a full structural change is needed.

What "Rename" Means in VSAM

A rename in VSAM terms means changing the catalog entry name. The data on the volume does not move; only the name by which the object is known in the catalog changes. So ALTER cluster-name NEWNAME(new-name) updates the catalog so that the cluster that was known as cluster-name is now known as new-name. Any program or JCL that opened the cluster by the old name must be updated to use the new name. The same idea applies to paths and alternate indexes: ALTER path-name NEWNAME(new-path-name) changes the path's catalog name; ALTER aix-name NEWNAME(new-aix-name) changes the AIX's catalog name.

Syntax for Renaming Different Object Types

The general form is ALTER entry-name NEWNAME(new-name). For a cluster you can use a generic so that the cluster and its components are renamed together. The following table summarizes the syntax for cluster, path, and AIX.

Renaming a Cluster Only

To rename just the cluster entry (the name you use in DSN=), use ALTER cluster-name NEWNAME(new-name). The data and index component names in the catalog are not changed; they remain cluster-name.DATA and cluster-name.INDEX (or whatever they were). So the cluster has a new name but its components still have the old cluster name in their names. That can be confusing. Often you want to rename the cluster and its components so that everything is consistent under the new name. For that you use the generic form NEWNAME(new-name.*).

1
2
3
  ALTER MY.OLD.PROD.KSDS -
    NEWNAME(MY.NEW.PROD.KSDS)
 

After this, the cluster is known as MY.NEW.PROD.KSDS. The component names (e.g. MY.OLD.PROD.KSDS.DATA) are unchanged unless you use the generic form below.

Renaming a Cluster and Its Components

To rename the cluster and all its components so that the new name is the high-level qualifier for both the cluster and its DATA and INDEX entries, use NEWNAME(new-name.*). The asterisk is a generic: the cluster and every component that matches the cluster name are renamed so that the first part of the name becomes new-name. For example MY.OLD.KSDS becomes MY.NEW.KSDS, MY.OLD.KSDS.DATA becomes MY.NEW.KSDS.DATA, and MY.OLD.KSDS.INDEX becomes MY.NEW.KSDS.INDEX. That keeps the relationship consistent and avoids having a cluster with one name and components with another.

1
2
3
  ALTER MY.OLD.PROD.KSDS -
    NEWNAME(MY.NEW.PROD.KSDS.*)
 

After this, the cluster is MY.NEW.PROD.KSDS and its components are MY.NEW.PROD.KSDS.DATA and MY.NEW.PROD.KSDS.INDEX. All references in JCL and programs must use MY.NEW.PROD.KSDS.

Renaming a Path or an Alternate Index

A path is only a catalog entry that points to an alternate index; renaming the path does not move any data. Use ALTER path-name NEWNAME(new-path-name). Applications that opened the file by the path name must then use the new path name. Renaming an alternate index is done with ALTER aix-name NEWNAME(new-aix-name). The AIX cluster and its components are then known by the new name. Paths that point to the AIX may need to be updated depending on how your catalog and IDCAMS handle the relationship; in some cases the path continues to point to the AIX by its new name, in others you may need to redefine the path or run additional steps. Check your documentation.

1
2
3
4
5
6
  ALTER MY.APPL.BY.DEPT.PATH -
    NEWNAME(MY.APPL.BY.DEPARTMENT.PATH)
 
  ALTER MY.APPL.AIX.DEPT -
    NEWNAME(MY.APPL.AIX.DEPARTMENT)
 

Requirements and Restrictions

Renaming fails or causes problems if certain conditions are not met. The following table lists the main requirements and what happens if they are not satisfied.

The "dataset not in use" rule is critical. If a batch job or CICS region (or any other address space) has the cluster, path, or AIX open, the rename can fail with a return code or can leave the catalog in an inconsistent state. Always ensure that no job has the object open when you run ALTER NEWNAME. For SMS-managed datasets, renaming can cause the system to re-evaluate the storage class and other SMS attributes; if the current STORCLAS has been removed from the SMS configuration, the rename can fail. In that case you may need to ALTER the cluster to set STORCLAS to a valid class before attempting the rename.

Order When Renaming Base Cluster with Path and AIX

If your base cluster has an alternate index and one or more paths, the order of renames can matter. In many environments, when you rename the base cluster (with NEWNAME(newname.*)), the catalog can update the AIX and path associations so they still point to the renamed base. In other cases you might rename in a specific order: for example rename the base cluster first, then the AIX, then the paths, and ensure that path definitions still point to the correct AIX. Documentation and behavior can vary by catalog type and IDCAMS level. For a full rename of a "sphere" (base cluster plus all its AIXs and paths) with strict control over every name, some installations use ADRDSSU (or an equivalent) with options that rename the entire sphere in one go. For simple cases—a cluster with no path or AIX—ALTER cluster-name NEWNAME(newname.*) is usually enough.

Example: Full Rename of a KSDS

Suppose you have a KSDS named MY.OLD.KSDS with no path or AIX. You want to rename it to MY.NEW.KSDS and have the components renamed as well. Ensure no job has MY.OLD.KSDS open, then run:

1
2
3
4
5
6
7
  //RENAME   EXEC PGM=IDCAMS
  //SYSPRINT DD SYSOUT=*
  //SYSIN    DD *
    ALTER MY.OLD.KSDS -
      NEWNAME(MY.NEW.KSDS.*)
  /*
 

After a successful run, the cluster is MY.NEW.KSDS and the components are MY.NEW.KSDS.DATA and MY.NEW.KSDS.INDEX. Update all JCL and programs to use MY.NEW.KSDS.

Step-by-Step: Renaming a Cluster

1. Ensure no job or region has the cluster (or path, or AIX) open. Coordinate with application owners if needed.
2. Decide the new name and confirm it does not already exist in the catalog.
3. If the cluster has path(s) and AIX, check your documentation for the recommended order (often: rename base with NEWNAME(newname.*), then AIX and paths if required).
4. Run IDCAMS with ALTER entry-name NEWNAME(new-name) or NEWNAME(new-name.*) for cluster and components.
5. Check the IDCAMS return code and SYSPRINT for errors (e.g. dataset in use, invalid STORCLAS, catalog not found).
6. Update all JCL and programs to use the new name. Retire or redirect any references to the old name.

When to Use Rename vs Delete and Recreate

Use ALTER NEWNAME when you only need to change the name and the structure (key, record size, CI size) stays the same. It is fast and does not require copying data. Use delete and recreate (DELETE, DEFINE CLUSTER, REPRO) when you need to change something that cannot be altered—for example key length, key offset, control interval size, or dataset type. In that case you define a new cluster with the new name and the new attributes, REPRO the data from the old cluster to the new one, then delete the old cluster and switch applications to the new name. So rename is for a simple name change; delete/redefine/REPRO is for a structural change that forces a new cluster.

Key Takeaways

• There is no separate RENAME command; use ALTER entry-name NEWNAME(new-name).
• The dataset must not be in use when you run ALTER NEWNAME.
• Use NEWNAME(new-name.*) to rename the cluster and its components so all names use the new qualifier.
• After a rename, update all JCL and programs to use the new name.
• On SMS systems, ensure STORCLAS is valid before renaming; otherwise the rename can fail.

Explain Like I'm Five

Renaming is like changing the label on a filing cabinet. The cabinet and the papers inside stay where they are; only the name on the label changes. Everyone who used to look for "Old Cabinet" now has to look for "New Cabinet." You have to do the relabeling when nobody is using the cabinet (dataset not in use). If you want the drawers to have new labels too (DATA and INDEX), you ask for the whole set to be relabeled (NEWNAME(newname.*)). After that, the old name doesn't work anymore—only the new name.

Test Your Knowledge