IDCAMS ALTER NEWNAME for user catalog in z/VSE 6.2

By Mikhail Zaslonko and Jens Remus.

VSE/VSAM IDCAMS provides a new functionality allowing to change a VSAM user catalog name with the PTF UD54395 for APAR DY47844 “ALTER NEWNAME USERCATALOG”. It allows to change a user catalog name without having to re-define it from scratch. This fulfills RFE 111771 “Allow ALTER NEWNAME for user catalog”. Additionally this functionality may also be helpful with the processes Rebuilding a Catalog and Migrating Catalogs that are described in the VSE/VSAM User’s Guide and Application Programming manual.

With the new functionality a user catalog name can be changed using the new USERCATALOG attribute of the IDCAMS ALTER command in conjunction with the NEWNAME parameter:

USERCATALOG

specifies that the object to be renamed is a user catalog. This parameter must be specified if you want to alter a name of a user catalog (to be used together with a NEWNAME parameter).
A user catalog can only be renamed if it is not in use by any other partition (or system). Changing the name of the master catalog (IJSYSCT, usually VSAM.MASTER.CATALOG) or the system user catalog (VSESPUC, usually VSESP.USER.CATALOG) is not allowed.

Note: If the user catalog name is changed, all existing labels referring the old catalog name will point to a non-existing catalog and thus fail when referred to by an application. The user needs to take care of such labels separately (i.e. ALTER does not perform this processing automatically).

Abbreviation: UCAT

Sample

Following is an example of using the new USERCATALOG attribute of the IDCAMS ALTER command to rename the user catalog OLD.USER.CATALOG to NEW.USER.CATALOG. Like before, when altering information that relates to a user catalog itself, the user catalog has to be specified as entryname and in addition either as job catalog (i.e. via label IJSYSUC) or referenced in the CATALOG parameter of the ALTER command.

// DLBL IJSYSUC,’OLD.USER.CATALOG’,,VSAM
// EXEC IDCAMS,SIZE=AUTO
   ALTER OLD.USER.CATALOG          -
         NEWNAME(NEW.USER.CATALOG) -
         USERCATALOG
/*

Catalog Migration Using DEFINE/REPRO/ALTER

Although you cannot copy a user catalog itself the following procedure can be used to move a user catalog and the required files to another volume using DEFINE, REPRO, and ALTER commands:

1. DEFINE the new user catalog on a new volume using a temporary catalog name that is not already in the system. Refer to the procedure described in the manual VSE/VSAM User’s Guide and Application Programming, section Definitions for Catalog Migration.
2. DEFINE any VSE/VSAM data spaces required on the new volume(s). Note that the define catalog operation already defines a data space on the catalog volume. Any space to be occupied by unique files should be left unallocated.
3. Stop any use of the source catalog. This includes shutting down any CICS partitions that are using the source catalog.
4. DEFINE all the files, excluding the alternate indexes and paths, using the original names from the source catalog.
5. REPRO every file onto the new volume. It is strongly recommended that the files being copied should not be opened for output by any other partition or system. For further details and other options to copy the files and their alternate indexes refer to the manual VSE/VSAM User’s Guide and Application Programming, section Migrating VSE/VSAM Files to Another Device.
6. Repeat steps 4 and 5 for all alternate indexes. Also DEFINE all paths using the original names from the source catalog.
7. DISCONNECT the source catalog entry from the system while it is still not used.
8. ALTER NEWNAME USERCATALOG the temporary catalog name of the new catalog to the source catalog name.

In case of a shared catalog stop any use of the source catalog on all systems sharing the catalog in step 3, perform steps 4 to 8 on one system only, and then DISCONNECT the source catalog entry from all other systems and CONNECT it again with the new volume name. Refer to Cross-Systems Sharing for shared catalog considerations.

This method allows to migrate a user catalog and its files to a new device type as well as perform the data reorganization during the move. Note that in the general case of suballocated VSAM files (non-unique files) existing labels do not need to be changed with this approach since the target catalog name remains the same. Other options would be Catalog Migration Using EXPORT/IMPORT and Catalog Migration Using BACKUP/RESTORE that are described in Migrating Catalogs. Note that the latter has some restrictions regarding changing the device type.

Possible Error Messages

The following error messages may occur during ALTER NEWNAME USERCATALOG processing:

• If the catalog is open in another partition (existing error message reused):
  IDC3028I DATA SET IN USEIDC3009I ** VSAM CATALOG RETURN CODE IS 184 - REASON CODE IS IGG0CLEX-4
• If the specified entryname is not a catalog (existing error message reused):
  IDC3190I 'USERCATALOG' PARAMETER INVALID WITH ENTRY TYPE
• If the catalog name specified with the NEWNAME parameter already exists (existing error message reused):
  IDC3013I DUPLICATE DATA SET NAME
• If the specified entryname is restricted as a system catalog reserved name (new error message):
  IDC3192I RENAMING MASTER CATALOG (IJSYSCT) OR SYSTEM USER CATALOG (VSESPUC) IS NOT ALLOWED
• In the exceptional case, ALTER NEWNAME USERCATALOG may fail at a point where the user catalog file name has already been changed but the entry in the master catalog has not been updated yet. In this case, the attempt to access the user catalog using its old name would lead to the error message:
  4A92I MISMATCH OF SPECIFIED AND REAL CATALOG FILE ID
SPECIFIED NAME=file_id1
BUT REAL NAME=file_id2
  In this case, the user catalog needs to be manually connected to the system with its new name (file_id2) using IMPORT CONNECT in order to complete the catalog rename process.

Documentation

The manuals VSE/VSAM Commands (sections “Catalog Entry Types that Can Be Altered”, “ALTER Parameters: Summary”, and “ALTER Parameters in Detail”), VSE/VSAM User’s Guide and Application Programming (section “Migrating Catalogs”), and z/VSE Messages and Codes Volume 2 have been updated.

I greatly appreciate your feedback via the z/VSE contact form.

Disclaimer: My posts and opinions are my own.

Originally published in Jens’ z/VSE Blog within the IBM Z and LinuxONE Community on IBM Community on July 21, 2021.