Preparing to migrate a single IBM MQ for z/OS queue manager

Review the z/OS and IBM MQ customization steps, and change any customizations before starting any queue managers at Version 9.2. Follow the steps to prepare a single IBM MQ queue manager on z/OS for migration.

Before starting

We can continue to run the queue manager on the previous version until it is ready to switch to Version 9.2. Preparing for the switch can be a long process. Switching from the earlier version to Version 9.2 is a quick process. The switch to Version 9.2 occurs when you restart the queue manager using the Version 9.2 libraries.

Tips:

1. To migrate applications, or the queue manager, when moving to a new release of IBM MQ, without changing STEPLIB, create data set aliases such as MQM.qmgr.SCSQLOAD, and reference them in JCL.

   Map the aliases to the real data sets, such as MQM.MQV920.SCSQLOAD.

2. We can use the z/OS command D GRS,SYSTEM,RES=(*,MQM.V920.SCSQLOAD) to display which jobs are using the specified data set, and so identify which jobs and JCL need to be changed.

About this task

The steps are based on the setup procedure for new queue managers; see Customizing your queue managers.

To prepare to migrate an IBM MQ queue manager on z/OS, we need to carry out the detailed steps in this topic, using the links within this overview.

1. Make your existing queue manager ready for migration; see step 1.
2. Enable NEWFUNC mode; see step 2
3. Install Version 9.2 and make target libraries available to all z/OS systems that are running queue managers, and grant access; see step 3.
4. Perform a back up operation of each queue manager in your enterprise; see step 4.
5. Run CSQ5PQSG if using queue sharing groups, see step 5.
6. Update the STEPLIB concatenations for Batch, TSO, and RRS applications; see step 6.
7. If we are planning to define a QMINI data set, see step 7
8. Update the libraries you added to connect CICS to the queue manager; see step 8.
9. Update the libraries for the operations and control panels to the Version 9.2 libraries; see step 9.
10. Update system libraries to format IBM MQ dumps using the Interactive Problem Control System (IPCS); see step 10.
11. Consider the migration of other server applications; see step 11.
12. Prepare the mqweb server for migration; see step 12.

Procedure

1. Make the IBM MQ configuration ready for migration, by applying the latest maintenance to the current version libraries. Refer to the Preventive Service Planning (PSP) bucket for the version of IBM MQ; see PSP Buckets - How to find them on Web.
2. If your existing queue manager is at Version 9.0, and is running with OPMODE(COMPAT,xxx) then recompile your ZPARMs so that OPMODE(NEWFUNC,900) is used. This ensures that if you perform the migration, and you subsequently have to backwards migrate, we will not end up with problems if you have enabled function which requires NEWFUNC mode, for example 64 bit buffer pools, or 64 bit log RBA, at Version 9.2.See the IBM MQ Version 9.0 topic, OPMODE on z/OS for more information.
3. Install Version 9.2, and make target libraries available to all z/OS systems that are running queue managers, and grant access. We must carry out the following procedure for each z/OS system.
   1. Copy the IBM MQ target libraries to the system, and install the early code for Version 9.2 (once for each z/OS system).
   2. APF authorize the load libraries and grant access to the data sets using your external security system. See APF authorize the IBM MQ load libraries for more information. Ensure that the APF lists in SYS1.PARMLIB are updated to ensure that any changes made dynamically remain in effect after an IPL.
   3. Make the Version 9.2 early code and target libraries available on each z/OS system that is running queue managers. This involves updating the LPA; see Update the z/OS link list and LPA for more information.Once this is done, the following message is displayed in the job log of all queue managers when they start up, indicating they are using the most recent version of early code:

      CSQ3111I <cpf> CSQYSCMD - EARLY PROCESSING PROGRAM IS V9.2 LEVEL 010-000

      If we are using AMS, also add CSQ0DRTM to the LPA as described in the previous link.
   4. Copy the file system zFS and mount it read only. You only need zFS if one of the following is installed:
      • IBM MQ for z/OS Unix System Services Components
      • IBM MQ for z/OS Managed File Transfer
      • IBM MQ for z/OS Unix System Services Web Components, or
      • IBM MQ for z/OS Connector Pack

      See the Program Directory for further information. Program Directories can be downloaded from the IBM Publications Center (see IBM MQ for z/OS Program Directory PDF files).

4. Perform a back up operation for each queue manager in your enterprise, so that we have a copy of all objects and JCL before you make any changes. This makes rolling back to the current system easier, if you require to do so.
   1. Back up the IBM MQ defined objects, for example using CSQUTIL COMMAND MAKEDEF(..) See Use the COMMAND function of CSQUTIL for more information.
   2. Back up:
      • Started task procedures for the queue manager, channel initiator and, if applicable, the AMS address space.
      • The Initialization input data sets used in the CSQINP1 and CSQINP2 concatenations
      • The system parameter module (ZPARM) libraries
      • The JCL libraries containing the configuration definitions for the queue manager
      • Other libraries containing queue manager configuration or procedures.

      Note: We might also make a back up of page sets, BSDSs, and active logs as a fallback option. See How to back up and recover page sets for more information on backing up IBM MQ resources.

5. If we are using queue sharing groups, run CSQ5PQSG. We must specify the MIGRATE QSG or MIGRATE DSG function, to verify that all queue managers in the QSG or DSG are at a version that is compatible with IBM MQ Version 9.2.0.
6. Update the libraries you added to STEPLIB concatenations, to make Batch, TSO, and RRS adapters available to applications, so that they can always load the highest version IBM MQ library in the system. Change the STEPLIB for the Batch, TSO, and RRS applications to reference the Version 9.2 libraries, then restart the applications.

   See Set up Batch, TSO, and RRS adapters for more information.

   IBM MQ libraries include:

   thlqual.SCSQANLx

   This library contains error message information for the national language. The letter 'x' represents the letter for the national language.

   thlqual.SCSQAUTH

   This library contains the code that the applications use.

   Notes: We can:

   1. Connect applications that reference Version 9.2 libraries in STEPLIB to a queue manager that is running on Version 9.2 or earlier. We must not connect applications that reference a STEPLIB from an earlier version to a queue manager running on a later version.
   2. Use the following command, replacing thlqual with the High Level Qualifier for the installation, to check which jobs are running with the specified library:

      TSO ISRDDN ENQ 'thlqual.SCSQANLE'

      We can then modify the JCL for those jobs accordingly.

7. If we are planning to define a QMINI data set, define the data set and update the queue manager start up JCL to add CSQMINI DD to point to your QMINI data set.
8. Update the libraries you added to connect CICS to the queue manager. We must update the IBM MQ libraries in the STEPLIB and DFHRPL concatenations of our CICS region JCL and restart CICS. You are then able to use the most recent IBM MQ features.

   The connection between IBM MQ and CICS is provided by CICS libraries that we must update. 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.

   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 Set up the CICS - IBM MQ adapter.

9. Update the libraries for the operations and control panels to the Version 9.2 libraries. For more information, see Set up the operations and control panels.Note: We can connect the operations and control panel that references Version 9.2 libraries to the queue manager that is running on Version 9.2, or earlier. We must not connect the operations and control panel that references IBM MQ libraries from an earlier version to a queue manager running on a later version.
10. Update system libraries to format IBM MQ dumps using the Interactive Problem Control System (IPCS). For more information, see Include the IBM MQ dump formatting member.
11. Migrate other software, such as WebSphere Application Server for z/OS, WebSphere Application Server for z/OS Liberty, IBM Integration Bus, or IMS to use Version 9.2 libraries.
    1. WebSphere Application Server for z/OS

       If we are running in an application server environment where a bindings connection is being used, we need to update the WAS STEPLIB with IBM MQ libraries.

       See IBM MQ libraries and the WebSphere Application Server for z/OS STEPLIB for further information.

       You also need to configure the IBM MQ messaging provider with native libraries from Version 9.2 of the IBM MQ installation; see Configure the IBM MQ messaging provider with native libraries for further information.

       Use the latest level of native libraries in USS.

    2. WebSphere Application Server for z/OS Liberty If we are running in an application server environment where a bindings connection is being used, we need to update the Liberty STEPLIB to use the updated IBM MQ for z/OS libraries.You should also update the wmqJmsClient.rar.location variable, and the wmqJmsClient nativeLibraryPath attribute, in the Liberty server.xml to point to the new path to the IBM MQ for z/OS USS components feature.Note: These steps also apply to IBM z/OS Connect EE.
    3. IMS

       For more information, see Set up the IMS adapter.

12. If we have configured the IBM MQ Console or REST API, you might need to prepare the mqweb server for migration.

    The mqweb server that hosts the IBM MQ Console and REST API can only connect directly to queue managers at the same version of IBM MQ.

    If you only have one queue manager on the z/OS system, we do not need to do anything now. We can migrate the existing mqweb server at the same time as the queue manager.

    If we have more than one queue manager on the z/OS system, that will be running at different versions of IBM MQ during migration, create a new mqweb server at the latest level.

    1. Create a new mqweb server by following the procedure in Create the mqweb server.
    2. Create a started task procedure for the new mqweb server by following the procedure in Create a procedure for the mqweb server.
    3. Copy any relevant configuration settings from the mqwebuser.xml configuration file of the existing server to the mqwebuser.xml file of the new mqweb server. The mqwebuser.xml file is in the WLP_user_directory/servers/mqweb directory, where WLP_user_directory is the directory that was specified when the crtmqweb script ran to create the mqweb server definition.

       Configure the new server to use different HTTP and HTTPS ports to any existing servers.

    4. Start the new mqweb server by issuing the MVS™ START procname command, where procname is the name of the new mqweb server started task procedure.

Results

We have prepared the IBM MQ queue manager on z/OS for migration.

What to do next

Follow the instructions in Migrating a single IBM MQ z/OS queue manager to Version 9.2 to migrate the queue manager. Parent topic: Migrating IBM MQ for z/OS - order of tasks