z/OS: Migration planning to the latest release

Create a migration plan for IBM® MQ for z/OS® to upgrade to the latest release.

1. Review the IBM MQ system requirements for the latest version.
   • See System requirements for IBM MQ.
2. Review all the changes in the product that affect you.
   See What's changed in IBM MQ 8.0 for further information.
3. Review performance changes.
   • Performance reports are published as Supportpacs; see IBM MQ - SupportPacs by Product.
4. 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 you 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.V8R0M0)
   

   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.

5. Plan to install the latest version early code, and activate for all queue managers on the LPAR.
   See Installing early code for more information.

   Note that:

   • Before migration, all systems that are running queue managers that you plan to migrate to the latest 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.
6. 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.V710.SCSQANLE))
   

   You 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 you can get all of the programs to refer to the new libraries at the same time.

7. Plan the sequence and timing of queue manager upgrades.
   • 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 latest version. You 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 Queue manager cluster migration.
   • Check that any products that require the previous version of the product also support the new version.
8. Plan to update any manual or automated procedures you have written with changes to messages and codes.
9. Plan to update applications that might be affected by changes.
   • Update the IBM MQ library in the application STEPLIB concatenations to the latest version.
   • Consider whether the application must be able to run on both the previous version and the latest version. You might be able to change the application to be compatible with both code levels. If you cannot, you can query the queue manager command level, and make the code conditional on the command level. Call MQINQ setting the MQIA_COMMAND_LEVEL selector.
10. Decide on what regression tests to perform before enabling the new function in the latest version.
    • The OPMODE parameter controls a staged migration from the previous version to the latest version.
    • Initially set OPMODE to (COMPAT,800) to make sure that you can go back to using an earlier version of the product. Once you are satisfied with the stability of the latest version, you can start to use the new functions available, which requires setting OPMODE to (NEWFUNC,800).
    • Include the procedures and applications you identified in steps 8 and 9 in your regression tests.
11. 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 latest versions.
    • The customization steps for migration are described in z/OS: Review and modify queue manager customizations from the previous release
12. 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 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 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'
13. Check that you are using a supported level of assembler or compiler.
    • You 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.
14. Plan any changes to libraries required by your applications and channel exits.
15. Plan to upgrade your IBM MQ MQI client installations to the latest version.
16. Plan to upgrade your client and server applications to use new functions in the latest version.
17. Plan to migrate other vendor software, such as WebSphere Application Server, or CICS® to use the latest version.
    • Update the IBM MQ libraries in the STEPLIB and DFHRPL concatenations of your CICS region JCL and restart CICS.

    Note:

    • CICS

      Update the IBM MQ libraries in the STEPLIB and DFHRPL concatenations of your CICS region JCL and restart CICS.

      Up to, and including CICS 3.2, the connection between IBM MQ and CICS is provided by IBM MQ. You must change the SCSQCICS and SCSQAUTH libraries in the DFHRPL concatenation provided by IBM MQ.

      After CICS 3.2, the connection between IBM MQ and CICS is provided by CICS libraries. Update the libraries, if you are using CICS Transaction Server for z/OS Version 3.2 or later. Without this change, you are not able to use the most recent IBM MQ features. You must change the SCSQCICS library in the DFHRPL concatenation provided by IBM MQ, and also the STEPLIB concatenation.

      Create separate CICS started procedure JCL. For each CICS region that is connected to an IBM MQ queue manager, ensure that there is a separate CICS started procedure JCL.

      This ensures that the modification of reference to a certain version of IBM MQ libraries in the CICS started procedure JCL only has impact for that single CICS region. In this way you can migrate one queue manager, and only the CICS region or regions connected to it, which makes staged migration possible.

      CICS STEPLIB has thlqual.SCSQAUTH, and DFHRPL has thlqual.SCSQCICS, thlqual.SCSQLOAD, and thlqual.SCSQAUTH. For more information, see Setting up the CICS- IBM MQ adapter

18. Review any other installed SupportPacs for their applicability to the latest version.