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

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.
   1. Refer to the Preventive Service Planning (PSP) bucket for your version of IBM MQ ; see PSP Buckets - How to find them on Web.
   2. Apply the migration and toleration PTFs to the version of the IBM MQ code that your enterprise uses; see IBM MQ Support, Migration PTFs.

      Note that the migration and toleration PTFs are also known as the backward migration and coexistence PTFs; they are the same PTFs.

      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.

      There is an additional category of TargetSystem-RequiredService.MQ.V8R0M0 enabling other products to run with IBM MQ 8.0.

2. Install the new code and make target libraries available to all MVS systems that are running queue managers, and grant access.
   You must carry out the following procedure for each MVS system.
   1. Copy the IBM MQ target libraries to the system, and install the early code for the new version (once for each MVS system).
      Activate the code for all of the queue managers on each MVS system that is running queue managers.

      This updates the LPA. See Update the z/OS link list and LPA for more information.

   2. APF authorize the load libraries and grant access to the datasets using your external security system.
      See APF authorize the IBM MQ load libraries for more information.
   3. Copy the file system zFS and mount it read only.

      You only need zFS, or older HFS, if the IBM MQ for z/OS Unix System Services Component is installed. See the Program Directory for further information. For download links for the Program Directories, see IBM MQ for z/OS Program Directory PDF files.

   Refresh all the queue managers so that they use the new early code using the command REFRESH QMGR TYPE(EARLY). See REFRESH QMGR for more information.

3. Perform a back up operation for each queue manager in your enterprise, so that you have a before 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. Backup your IBM MQ defined objects, for example using CSQUTIL COMMAND MAKEDEF(..)
      See Issuing commands to Websphere MQ (COMMAND) for more information.
   2. Backup:
      • The MSTR and CHINIT started procedure jobs
      • The Initialization input datasets used in the CSQINP1 and CSQINP2 concatenations
      • The system parameter module (ZPARM) libraries
      • Other tasks as necessary.

      Note: You might also make a back up of page sets, BSDSs, and active logs as a fallback option. See How to backup and recover pagesets for more information on backing up IBM MQ resources.
4. Check that MSTR and CHIN address spaces run under user IDs that have OMVS segments defined, with a valid UID, to enable calling Unix System Services (USS).
5. Restart your IBM MQ system to run with the migration and toleration PTFs.
   1. Restart the queue managers and monitor the whole system in your enterprise closely to ensure that there are no issues.
      Depending on the size and complexity of your enterprise this can take a considerable length of time, so you must plan for this in your migration schedule.
6. Review the usage of pageset 0.
   Note that you can ignore this step if your enterprise is already using IBM MQ V7.1.
   Issue the operator command /cpf DISPLAY USAGE PSID(0), where cpf is the command prefix for the queue manager's subsystem, to get a report on pageset 0 usage.

   The size of queue definitions increased in IBM MQ V7.1. During migration to this version, or later versions of the product from an earlier version of the product, queue definitions stored on pageset 0 are rewritten.

   The rewrite is carried out as a single transaction when the queue manager is first migrated to IBM MQ V7.1, or later.

   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'.

7. Migrate your Db2 tables for each Db2 data sharing group.

   You must do this for each Db2 data sharing group, as multiple QSGs can use the same Db2 tables.

   You can use IBM provided samples shipped in the new version of the product to perform this task. Some Db2 table definitions are updated, and some new Db2 tables are created for the migrated version of the queue manager.

   Notes:

   1. You must have applied the migration and toleration PTFs to all the queue managers, before migrating the Db2 tables.
   2. Every queue manager in the QSG needs to be restarted at the current release, with the PTFs applied.
   3. At no stage is an outage of the entire queue-sharing group required.
   4. Migrate your Db2 tables.

      If the jobs described fail because of a Db2 locking problem, it might be due to contention for a Db2 resource. Locking is more likely, if the system is being heavily used. Resubmit the job later, preferably when the system is lightly used or quiesced.

      See steps 5 and 6 of Set up the Db2 environment.

   5. Use the CSQ45* jobs in the newest thlqual.SCSQPROC supplied with the version of the product to which you are migrating.
      Note that the JCL to use depends on the highest version of IBM MQ in the Db2 tables.

      1. If the Db2 tables have IBM WebSphere® MQ 7.1 queue managers, use CSQ4571T. If the Db2 tables have IBM WebSphere MQ 7.0 queue managers, use CSQ4570T.
      2. Customize the CSQ45* sample.

         The header information in CSQ45* describes how to customize the sample.

      3. Run the customized CSQ45* job.
      4. Customize the CSQ45BPL and CSQ45GEX samples, in thlqual.SCSQPROC

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

      5. Run the customized jobs, CSQ45BPL and CSQ45GEX.

         If you need to rebind the plans or packages, see Step 2 in Migrating queue sharing groups from a previous release for further information.

   6. If you have multiple QSGs in the same data sharing group (DSG) you need to check each QSG to see if each member meets its migration criteria. Use sample JCL CSQ45MQS in conjunction with CSQ4571T.

      See the JCL header description for further information.

8. Add the new coupling facility (CF) definition.
   Repeat this step for each QSG. Note that you can ignore this step if your enterprise is already using IBM MQ V7.1.

   Starting with IBM MQ V701, a new CF structure is required; see Set up the coupling facility for information on how to add such a definition.

   The correct process to migrate SYSTEM.QSG.CHANNEL.SYNCQ, from a normal application CF structure, to system CF structure CSQSYSAPPL structure is:

   1. Stop the channel initiator (CHINIT) on all QSG queue managers, so that no channels are running.
   2. Copy the messages in SYSTEM.QSG.CHANNEL.SYNCQ to a temporary dataset, using CSQUTIL COPY.
   3. Delete SYSTEM.QSG.CHANNEL.SYNCQ from the repository.
   4. Define SYSTEM.QSG.CHANNEL.SYNCQ with CFSTRUCT(CSQSYSAPPL).
      As this is a shared queue, it only needs to be defined once per QSG. Note that you can define this queue from any queue manager within the QSG.
   5. Reload the SYNCQ messages from the temporary dataset, back to the newly defined shared queue, using CSQUTIL LOAD.
   6. Perform the other migration steps, and then restart CHINIT to make the changes taking effect.
9. Migrate server applications.

   Java or JMS applications running on the same host with IBM MQ connect to queue managers in bindings mode. This is a cross-memory connection. In this mode, applications need to update their STEPLIB concatenations, so that they can always load the highest version IBM MQ library in the system.

   Note, that if a z/OS Java or JMS application is running under WebSphere Application Server, the application can use client mode as an alternative to bindings mode.

   IBM MQ libraries include:

   thlqual.SCSQANLx

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

   thlqual.SCSQAUTH

   This library contains the code that the applications use.

   Server applications for IBM MQ can include:

   • Batch applications
   • Control panels in ISPF
   • IMS
   • Interactive problem control system (IPCS)
   • RRS adapter, including Db2 stored procedures.
   • TSO
   • Additionally, WebSphere Application Server for z/OS, IBM Integration Bus, and CICS®.
   1. You can use the "TSO ISRDDN ENQ ' thlqual.SCSQANLE'" command, replacing thlqual with the High Level Qualifier for your installation, to check which jobs are running with the specified library. You can then modify them accordingly.
   2. Update STEPLIB in the application JCL, and refer to the new IBM MQ libraries.
   3. Restart these applications.
      For further information, see:

      • Set up Batch, TSO, and RRS adapters
      • Setting up the IMS adapter
      • Set up the operations and control panels
      • Include the IBM MQ dump formatting member
   4. Migrate other software, such as WebSphere Application Server, IBM Integration Bus, or CICS to use the version of IBM MQ that you need.
      • 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

      • WAS 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 the new version 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 USS.

      Note that you can make use of a DFP ALIAS for convenience. Create data set aliases such as MQM.SCSLOAD, and reference them in JCL. Map the aliases to the real data sets, such as MQM.V700.SCSLOAD or MQM.V710.SCSLOAD.

      Change the aliases to switch between the two sets of target libraries. With the aliases, you can start applications or the queue manager when moving to a new release of IBM MQ without changing the STEPLIB JCL.

10. Advanced Message Security (AMS)

    If the queue manager is configured to use Advanced Message Security (AMS) perform the steps in the Preparing to migrate Advanced Message Security section of the Migrating Advanced Message Security topic.