Plan to migrate IBM MQ to a later version on z/OS

Create a migration plan for IBM MQ for z/OS® to migrate to the later version.

Before you begin

If there are concepts about migration we do not understand, see Migration concepts and methods.

If you are migrating to Version 9.0 from Version 7.0.1, you should first migrate to Version 7.1.

About this task

Use the following steps as a guide to creating your own plan to migrate your queue managers to a later version. Incorporate the task to migrate a queue manager, Migrating IBM MQ for z/OS - order of tasks, into your plan.

Migration plan overview for your enterprise

Migration phase	Required tasks
Phase I, before migration. See Preparing to migrate a single IBM MQ for z/OS queue manager for further information.	Preparing each queue manager in your enterprise for migration.
Phase II, migrate each single queue manager in the order listed. See Migrating a single IBM MQ z/OS queue manager to the next version of the product for further information.	Carry out this process for each queue manager: For queue managers in a cluster, migrate full repository queue managers before migrating any partial repository queue managers. Migrate z/OS queue managers in a queue-sharing group (QSG) before queue managers that are not in a QSG.
Phase III, post migration. See Post migration tasks for further information.	Carry out a full regression test, and then explore the new function available to you. Optionally, at any time in the process, migrate your client libraries if necessary, recompile your clients using the additional features provided by the new version, and deploy the clients.

Migration phase

Required tasks

Phase I, before migration. See Preparing to migrate a single IBM MQ for z/OS queue manager for further information.

Preparing each queue manager in your enterprise for migration.

Phase II, migrate each single queue manager in the order listed. See Migrating a single IBM MQ z/OS queue manager to the next version of the product for further information.

Carry out this process for each queue manager:

For queue managers in a cluster, migrate full repository queue managers before migrating any partial repository queue managers.
Migrate z/OS queue managers in a queue-sharing group (QSG) before queue managers that are not in a QSG.

Phase III, post migration. See Post migration tasks for further information.

Carry out a full regression test, and then explore the new function available to you.

Optionally, at any time in the process, migrate your client libraries if necessary, recompile your clients using the additional features provided by the new version, and deploy the clients.

Procedure

Review the IBM MQ system requirements for the later version.
- See System requirements for IBM MQ.
Review all the changes in the product that affect you. For further information, see:
- What's new and changed in IBM MQ Version 9.0
- What's new and changed in Version 9.0.x Continuous Delivery
Review performance changes. See IBM MQ Family - Performance Reports.
Review the backward and coexistence (or migration and toleration) PTFs for your current version of the product. See IBM MQ Support, Migration PTFs.
These PTFs must be applied to your current version of the product to enable you to revert your queue managers to the current version, after the queue managers have been started at the target version.

Note, that we can have different versions of queue managers coexisting in the same queue-sharing group.
If you are unsure which migration PTFs you require, run the following command SMP/E:
```
REPORT MISSINGFIX ZONES(mqtgtzone) FIXCAT(IBM.Coexistence.MQ.V9R0M0)
```
See FIXCAT and IBM MQ Migration Installation for further information. Attention: If a PTF requires a rebind of Db2® plans, the PTF is shipped with ++HOLD(ACTION), indicating the need for this process. In such a case, see Migrating Db2 tables to bind the plans before starting migration.
Other FIXCAT categories are listed in IBM Fix Category Values and Descriptions.
Plan to install the later version early code, and activate for all queue managers on the LPAR. See Install early code for more information. Note that:
- Before migration, all systems that are running queue managers that you plan to migrate to the later version must have the early code for that version installed and running. Queue managers in queue sharing groups that contain queue managers that are to be migrated, must also be running the early code.
- A queue manager must use the early code from the same release level, or a later release level.
Consider using aliases for the IBM MQ libraries. For example, use the IDCAMS utility with the DEFINE command:
```
DEFINE ALIAS(NAME(MQM.SCSQANLE)RELATE(MQM.V900.SCSQANLE))
```
We can use MQM.SCSQANLE, where applicable, in your STEPLIB, and it resolves to the actual data set.
When you migrate to a new release, change the alias definition, rather than changing all the places in your JCL where the library is referenced.

This process has the most benefit for your server application programs, because we can get all of the programs to refer to the new libraries at the same time.
Plan the sequence and timing of queue manager migrations.
- You must install the backward and coexistence (or migration and toleration) PTF to bring the previous version queue managers up to the latest maintenance level for that version.
- You must install the PTF on all members of a queue sharing group, before you migrate any queue managers to the later version. We can install the PTF one member at a time, leaving the other members running.
- If the queue manager is a member of a queue manager cluster, you must consider the order of migration of queue managers in the cluster; see Migrating a queue manager cluster.
- Check that any products that require the previous version of the product also support the new version.
Plan to update any manual or automated procedures we have written with changes to messages and codes.
Plan to update applications that might be affected by changes. Update the IBM MQ library in the application STEPLIB concatenations to the later version.
Consider whether the application must be able to run on both the previous version and the later version. You might be able to change the application to be compatible with both code levels. If we cannot, we can query the queue manager command level, and make the code conditional on the command level. Call MQINQ setting the MQIA_COMMAND_LEVEL selector.
If you are migrating to a Long Term Support (LTS) release, decide on what regression tests to perform before enabling the new function in the later version. The OPMODE parameter controls a staged migration from the previous version to the later version.
Do not change OPMODE initially, when migrating to an LTS release, to make sure that we can go back to using an earlier version of the product, and that all the functions that were available before migration will still be available after migration.

If you are migrating from IBM WebSphere MQ Version 7.1 to IBM MQ Version 9.0, once you are satisfied with the stability of the later version, we can start to use the new functions. To use the new functions, you must set OPMODE to (NEWFUNC,900).

There are no new functions in IBM MQ Version 9.0 that are controlled by OPMODE, therefore if you are migrating from IBM MQ Version 8.0 to IBM MQ Version 9.0, setting OPMODE to (NEWFUNC,900) does not enable any new functions.

Backwards migration from a Continuous Delivery release CD release is not possible. If you are migrating to a CD release for the first time, you must set OPMODE to (NEWFUNC,90x) as part of the migration procedure, where x is the modification number.

Include the procedures and applications you identified in steps 8 and 9 in your regression tests.
Review the tasks to customize z/OS, and the queue manager. Plan how to change the queue manager definitions and started task JCL to migrate your queue managers to the later versions.
Review the usage of page set 0. Issue the operator command cpf, /cpf DISPLAY USAGE PSID(0) to obtain a report on pageset 0 usage.
The size of queue definitions increased in IBM WebSphere MQ Version 7.1. During migration queue definitions stored on pageset 0 are rewritten if you are migrating from a previous release. The rewrite is carried out as a single transaction when the queue manager is first migrated to IBM WebSphere MQ Version 7.1.

Ensure that there is enough space available on pageset 0 to create a copy of the queue definitions while migration is taking place. Typically, 60% free space on pageset 0 before migration is sufficient. However, the use of EXPAND(SYSTEM) on the pageset definition allows for automatic expansion as required. If there is insufficient space on pageset 0 during migration, the queue manager abends with completion code X'5C6' and reason code X'00C91900'.
Check that you are using a supported level of assembler or compiler. We can write IBM MQ applications using any compiler capable of generating standard OS linkage to the IBM MQ stub routines.Some of the data types used by IBM MQ API calls are not supported on some older compilers. You might require a more recent compiler. The following limitations are known:
1. Assembler copy books contain blank lines, which are not tolerated by assemblers earlier than HLASM.
2. Some older releases of PL/I do not support fixed bin(63) type. A macro defines such fields as char(8) when an earlier compiler is detected.
3. Some older releases of COBOL do not support function-pointers, which are used by the MQCB API.
Plan any changes to libraries required by our applications and channel exits.
Plan to migrate your IBM MQ MQI client installations to the later version.
Plan to migrate your client and server applications to use new functions in the later version.
Plan to migrate other vendor software, such as WebSphere Application Server, or CICS® to use the later version. Update the IBM MQ libraries in the STEPLIB and DFHRPL concatenations of your CICS region JCL and restart CICS.
Review any other installed SupportPacs for their applicability to the later version.

What to do next

Do the task, Preparing to migrate a single IBM MQ for z/OS queue manager. If you must restore a queue manager to the previous version, see Reverting a queue manager to a previous release on z/OS.

When you are confident existing applications are running without migration problems on the later version, plan to update OPMODE to (NEWFUNC,900) to enable new function, if you migrated from IBM WebSphere MQ Version 7.1 to IBM MQ Version 9.0.0 LTS release.