Migrating a single IBM MQ z/OS queue manager to the next version of the product

Carry out the instructions in this topic to migrate a single IBM MQ queue manager on z/OSĀ®,


To migrate an IBM MQ queue manager on z/OS to a different version, you need to carry out the:

  • Process described in Preparing to migrate a single IBM MQ for z/OS queue manager
  • Detailed steps in this topic, using the links within this overview.
    1. Update the initialization input data sets; see step 1.
    2. Stop or disconnect the applications; see step 2
    3. Stop the queue manager and its channel initiator; see step 3
    4. Update STEPLIB for the queue manager and the channel initiator; see step 4.
    5. Update the target version system parameter module (ZPARM); see step 5
    6. Configure Advanced Message Security; see step 6
    7. Review the security control of your system; see step 7
    8. Start the queue manager; see Step 8
    9. Optionally, revert the queue manager to a previous version; see step 9


Procedure

  1. Update the initialization input data sets. Each IBM MQ queue manager gets its initial definitions from a series of commands contained in the IBM MQ initialization input data sets. These data sets are referenced by the Data Definition (DD) names CSQINP1 and CSQINP2 defined in the queue manager started task procedure.

    See Customize the initialization input data sets.

    The samples supplied for the initialization input data sets can change between versions of IBM MQ. You must review the customization we have made previously to CSQINP1 and CSQINP2, and merge them into the initial definitions provided with the latest version of the product. See CSQINP1 and CSQINP2 input data sets changed on z/OS for more information.

    Secure the server-connection channels used by clients; see Securing remote connectivity to the queue manager.

    Attention: DEFINE SUB for SYSTEM.DEFAULT.SUB is no longer permitted in the CSQINP2 input data set. DEFINE SUB commands can instead be issued from the CSQINPT input data set. The CSQINPT input data set is processed each time the publish/subscribe engine is started, either during queue manager startup, or when the publish/subscribe engine is started with the ALTER QMGR PSMODE(ENABLED) command. See Issuing commands to IBM MQ for z/OS for more information on using the CSQINPT input data set.
  2. Stop or disconnect all the applications using the queue manager (for example, CICSĀ®, IMS, or batch) and the IBM MQ channels that are connected to other queue managers.
  3. Stop the queue manager and its channel initiator.
  4. Update STEPLIB for the queue manager (MSTR) and the channel initiator (CHINIT). Update the start procedure and CHINIT JCL.
    1. Update your procedure to start the queue manager.

      • IBM MQ now uses z/OS memory objects above the bar for some functions. You must allow the queue manager to access storage above the bar.
      • Your installation might have customized the SMFPRMxx member of SYS1.PARMLIB, or the IEFUSI exit to provide a default limit for jobs using virtual storage above the 2 GB bar. Check these limits give sufficient memory for a queue manager. A reasonable starting allocation is 2 GB. The message CSQY220I displays the amount of virtual storage currently used and available.
      • If your installation does not have a default limit for storage above the bar, or if you want to use a different limit for your queue manager, we can provide a queue manager-specific restriction on the amount of virtual storage available above the bar for memory objects by coding a MEMLIMIT parameter on the JCL of the queue manager stored procedure, xxxxMSTR, for example:
      //PROCSTEP EXEC PGM=CSQYASCP,REGION=0M,MEMLIMIT=2G
      

      You must allow the queue manager to access storage above the bar because IBM MQ uses memory above the bar.

      If insufficient storage is available above the bar, the queue manager reports this when starting, and stops.

    2. Update your procedures for the channel initiator.

  5. If migrating to a Continuous Delivery (CD) release for the first time, you must configure the OPMODE parameter in the system parameter module (ZPARM) to start in new function mode. For example, OPMODE=(NEWFUNC,901) Important: Do not update ZPARM at this stage when migrating to a Version 9.0.0 Long Term Support (LTS) release.

    For further details, see OPMODE.

  6. If the queue manager is configured to use Advanced Message Security (AMS), perform the steps in Migrating Advanced Message Security.
  7. Review your security control for queue sharing groups, the channel initiator, and all queue managers accessing the coupling facility list structures.
  8. Start the queue manager. Test that everything is working correctly and, if it is, start the channel initiator. If there is a problem starting the queue manager, consider reverting the queue manager to a previous version; see step 8.
  9. If a problem occurs when starting the queue manager, you might need to consider backward migration; see Reverting a queue manager to a previous release.


Results

You have migrated your IBM MQ for z/OS queue manager to the latest release.


What to do next

Follow the instructions in Post migration tasks to complete the migration process.