Reverting a queue manager to a previous version on z/OS

After migrating to IBM® MQ for z/OS® 10.0.0 LTS or IBM MQ for z/OS 10.0.0 CD, from either IBM MQ for z/OS 9.4.0 or IBM MQ for z/OS 9.3.0, you can backward migrate, or fallback, to the version you were using prior to migration, using the BACKMIG option on the START QMGR command. Backwards migration is not supported for a CD release such as IBM MQ for z/OS 9.3.5.

Before you begin

Certain function available in IBM MQ for z/OS 10.0 can affect the ability to backwards migrate. These functions are not enabled by default, but if you have enabled these functions, you need to disable them prior to performing backwards migration.

You should not exploit new IBM MQ for z/OS 10.0 functions, until you are sure that you will not need to perform backwards migration.

Migrating back to IBM MQ for z/OS 9.4.0

Before performing backwards migration the following changes might be needed.

Any channels that have been adjusted to have a CONNAME longer than 48 characters must be changed to use a CONNAME less than or equal to 48 characters. If the CONNAME is not changed, then backwards migration of the channel results in the CONNAME being replaced with blank characters, and the message CSQY046I (see Initialization procedure and general services messages (CSQY...)) is issued. Before using the channel, the CONNAME needs to be updated to a suitable value, for example an IP address or a shorter hostname.

If IgnoreSeqNumberMismatch (see The QMINI data set) has been set in the QMINI data set, then the channels stanza needs to be removed from the data set.

The OTELTRAC and OTELPCTL parameters no longer apply and, for private and copy object definitions and the queue manager object, the new options are deleted at the point of backwards migration. Any shared queues with OTELPCTL(AUTO) defined should be changed back to OTELPCTL(QMGR) to prevent inconsistencies in behavior across the queue sharing group.

If the value of OUTBUFF (see Using CSQ6LOGP) has been increased beyond 4000, it should be changed back to 4000 and the system parameters recompiled.

Migrating back to IBM MQ for z/OS 9.3.0

Information described in the preceding Migrating back to IBM MQ for z/OS 9.4.0 section applies.

When migrating back to IBM MQ for z/OS 9.3.0, the first-class CAPEXPRY attribute no longer applies to any object definitions, and is deleted at the point of backwards migration. If you want to maintain these CAPEXPRY values, identify any objects with the first-class CAPEXPRY attribute set, and revert to using the CUSTOM attribute before migrating.

For example, if MY.QUEUE has a CAPEXPRY value of 5000:

ALTER QL(MY.QUEUE) CAPEXPRY(NOLIMIT) CUSTOM('CAPEXPRY(5000)')

Attention: It is not a supported configuration to leave the first-class CAPEXPRY attribute set on a shared object if any queue managers in the queue sharing group are being backwards migrated. This configuration might lead to both the first-class CAPEXPRY and CUSTOM CAPEXPRY attributes being set at the same time.

In this instance, the first-class attribute is always used by the queue managers that do support it, and the CUSTOM attribute is used by those that do not. Therefore, if any queue managers are being backwards migrated, only the CUSTOM CAPEXPRY value should be set, to avoid confusion.

About this task

A queue manager can only be backwards migrated if it outputs the CSQY039I message at start up. In this case you can use the information in this topic to perform the backwards migration.

Backwards migration is normally only performed immediately after a migration fails for some reason. However, it is possible to perform backwards migration at any time if the CSQY039I message is output at queue manager start up.

Notes:

After performing a START QMGR BACKMIG(vrm), the queue manager is ready to be started at the specified level.
If, instead, you start the queue manager at a higher version level than was specified for the BACKMIG operation, the queue manager forward-migrates the queue manager to the higher version, and it is no longer possible to backwards migrate unless you repeat the START QMGR BACKMIG operation.
The BACKMIG operation makes direct changes to the page sets of IBM MQ and the objects stored on them. This means that you can restart the queue manager at the specified BACKMIG version, even if an IPL occurs before queue manager restart, or if the queue manager is started on a different LPAR.

If a queue manager issues the CSQY040I message at start up, backwards migration is not supported, and the procedure described in the following text is not applicable. If you have a back up of the queue manager data, prior to the migration, you could use that data to start the queue manager up at the earlier release.

Procedure

Ensure that the queue manager does not have any offline page sets.
If it does, use the command CSQUTIL FORMAT to bring the page sets back online.
Shut the queue manager down cleanly.
Run the command START QMGR BACKMIG(vrm) where vrm is the version, release and modifier value of the release previously migrated from, for example 930.
This value is output in the CSQY039I message at queue manager start up.
Attention: You need to remove the period characters from the message output.

You should include the PARM parameter, if it is used usually with the START QMGR command.
The queue manager starts up, rewrites its data in a format suitable for backwards migration, and shuts down. If the command processes successfully, the CSQY045I message is output.
If the CSQY043E message is output, examine the messages displayed to resolve the problem and retry the command again.
Switch back to use the MSTR and CHINIT started procedure JCLs with the IBM MQ for z/OS 9.4.0 or IBM MQ for z/OS 9.3.0 libraries, as required.

If data set aliases are being used for load libraries, switch the aliases to refer to the IBM MQ for z/OS 9.4.0 or IBM MQ for z/OS 9.3.0 libraries.

For example, an alias named MQM.MQP1.SCSQLOAD, referring to MQM.MQV100.SCSQLOAD, needs to be changed to refer to MQM.MQV940.SCSQLOAD or MQM.MQV930.SCSQLOAD, as required.
Revert to using the system parameter module (CSQZPARM) with IBM MQ for z/OS 9.4.0 or IBM MQ for z/OS 9.3.0, prior to migration, and linking to the IBM MQ for z/OS 9.4.0 or IBM MQ for z/OS 9.3.0 code, as required.
Verify the backwards migration by starting the queue manager, channel initiator and, listener or listeners separately.
Check for, and resolve, any errors that occur during start up.
Once all three components start up cleanly, you can combine the start up of the three components, if required.
Verify correct functioning of existing applications.

Results

Your queue manager will now be running at the version of code it was originally migrated from.

Note: It is not necessary to revert the early code to the previous version, for this installation, when reverting your queue manager to an earlier version.

Early code refers to the IBM MQ load modules that must be loaded into the Link Pack Area (LPA) for IBM MQ to act as a z/OS subsystem. When a command is issued to a queue manager, or when an application connects to a queue manager, the first action taken by the IBM MQ system is to load the early code.

The LPA must contain the IBM MQ early code modules from the latest version of IBM MQ running on the system. For example, if an IBM MQ for z/OS 10.0 and IBM MQ for z/OS 9.4.0 queue manager run on the same system, the early code for IBM MQ for z/OS 10.0 must be loaded in the LPA.

For more information, see Early code.