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 IBM MQ for z/OS 10.0. Follow the steps to prepare a single IBM MQ queue manager on z/OS for migration.

1. Make your IBM MQ configuration ready for migration.

   Apply the latest maintenance to the current version libraries. See the Preventive Service Planning (PSP) bucket for your version of IBM MQ; see PSP Buckets - How to find them on Web.

2. Install IBM MQ for z/OS 10.0, and make target libraries available to all z/OS systems that are running queue managers, and grant access.

   Complete the following sub-steps for each z/OS system. If migrating a member of a queue sharing group, upgrade the early code on all LPARs that host a member of the group, before you migrate any members of the group.

   1. Copy the IBM MQ target libraries to the system, and install the early code for IBM MQ for z/OS 10.0 (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 IBM MQ for z/OS 10.0 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 V10.0.0 LEVEL 010-000

      If you are using Advanced Message Security (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
      • IBM MQ for z/OS Connector Pack

      See the Program Directory for further information. For download links for the Program Directories, see IBM MQ for z/OS Program Directory PDF files.
3. Perform a back up operation for each queue manager in your enterprise, so that you have a copy of all objects and JCL before you make any changes.

   This makes rolling back to the current system easier, if you need to do so.

   1. Back up your IBM MQ defined objects, for example using CSQUTIL COMMAND MAKEDEF(..)
      See Using 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 your queue manager
      • Other libraries containing queue manager configuration or procedures.

      Note: You 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.
4. If you are using queue sharing groups, migrate the Db2® tables.

   IBM MQ 10.0 introduces a new column into several tables used by queue sharing groups. To add these new columns, customize and run the CSQ459TB sample in hlq.SCSQPROC. The sample contains instructions on how it should be customized and run.

5. If you are using queue sharing groups, bind, and grant execute authority for the Db2 plans.

   Customize and run the CSQ45BPL and CSQ45GEX samples in hlq.SCSQPROC. Tailor these members to your environment, using your Db2 subsystem names and data set names.

   The header information in CSQ45BPL and CSQ45GEX describes how to customize the samples:

   • CSQ45BPL of hlq.SCSQPROC contains the plan names required for the latest version of IBM MQ
   • CSQ45GEX of hlq.SCSQPROC contains the authorities required

   See steps 5 and 6 of Set up the Db2 environment.
6. If you are using queue sharing groups, run CSQ5PQSG.

   You 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 for z/OS 10.0.

7. 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 IBM MQ for z/OS 10.0 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 your national language, where x is the language letter:

   • C, for Chinese
   • E, for US English mixed case
   • F, for French
   • K, for Japanese
   • U, for US English uppercase

   thlqual.SCSQAUTH

   This library contains the code that the applications use.

   Notes: You can:

   1. Connect applications that reference IBM MQ for z/OS 10.0 libraries in STEPLIB to a queue manager that is running on IBM MQ for z/OS 10.0 or earlier. You 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 your installation, to check which jobs are running with the specified library:

      TSO ISRDDN ENQ 'thlqual.SCSQAUTH'

      You can then modify the JCL for those jobs accordingly.
8. If you 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.
9. Update the libraries you added to connect CICS® to the queue manager.

   You must update the IBM MQ libraries in the STEPLIB and DFHRPL concatenations of your 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 you 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 Setting up the CICS - IBM MQ adapter.

   Note: You can connect applications that reference IBM MQ for z/OS 10.0 libraries in STEPLIB to a queue manager that is running on IBM MQ for z/OS 10.0 or earlier. You must not connect applications that reference a STEPLIB from an earlier version to a queue manager running on a later version.
10. Update the libraries for the operations and control panels (CSQOREXX) to the IBM MQ for z/OS 10.0 libraries.

    For more information, see Set up the operations and control panels.

    Note: You can connect the operations and control panel that references IBM MQ for z/OS 10.0 libraries to the queue manager that is running on IBM MQ for z/OS 10.0, or earlier. You 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.
11. 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.

12. Migrate other software to use IBM MQ for z/OS 10.0 libraries.

    Migrate software such as WebSphere® Application Server for z/OS, Liberty, IBM Integration Bus, or IMS.

    1. WebSphere Application Server for z/OS

       If you are running in an application server environment where a bindings connection is being used, you 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 IBM MQ for z/OS 10.0 of the IBM MQ installation; see Configuring the IBM MQ messaging provider with native libraries for further information.

       Use the latest level of native libraries in z/OS UNIX System Services.

    2. WebSphere Application Server for z/OS Liberty
       If you are running in an application server environment where a bindings connection is being used, you 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 z/OS UNIX System Services components feature.
    3. IMS

       For more information, see Setting up the IMS adapter.

    Note: You can connect applications that reference IBM MQ for z/OS 10.0 libraries in STEPLIB to a queue manager that is running on IBM MQ for z/OS 10.0 or earlier. You must not connect applications that reference a STEPLIB from an earlier version to a queue manager running on a later version.
13. If you 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, you do not need to do anything now. You can migrate the existing mqweb server at the same time as the queue manager.

    If you 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.