z/OS: Review and modify queue manager customizations from the previous release

Review the z/OS® and IBM® MQ customization steps, and change any customizations before starting any queue managers with the libraries of the latest version.

Steps 1 to 10 are z/OS customization tasks.

Steps 11 to 16 are IBM MQ customization tasks.

1. Review that all the load libraries that must be APF authorized are authorized.
   • See Task 2: APF authorize the IBM MQ load libraries.
2. Update the LPA libraries with the new version of early code libraries.
   • See Task 3: Update the z/OS link list and LPA.
   • This step is unnecessary if you update the IBM MQ early code in all the LPARs as part of bringing your previous version IBM MQ libraries up to the latest maintenance level; see step 3.
   • You must activate the early code with an IPL, or restart the queue manager after issuing the following command.

   REFRESH QMGR TYPE(EARLY)
   

   Note: As part of the update you are asked to stop the queue manager. While the queue manager is stopped, you must check the qmgr.REFRESH.QMGR security profile is set up, refresh the queue manager and restart it.
3. Make your configuration of the previous version ready for migration.
   1. Apply current maintenance to the current version libraries.
      • Refer to the Preventive Service Planning (PSP) bucket for the current version of your product; see PSP Buckets - How to find them on Web.
   2. Apply the latest version migration and toleration ¹ PTFs to the previous version code; see IBM MQ Support, Migration PTFs.
   3. If required by any of the PTFs, make Db2® configuration changes and rebind Db2.
      • See the appropriate section in Task 9: Select and set up your coupling facility offload storage environment.
   4. Install the early code for the latest version.
      • Replace the early code.
   5. Make the latest version early code and earlier version target libraries available on all the LPARs that are running queue managers.
      • If the queue manager is a member of a queue-sharing group, update all the systems in the group.
   6. Restart IBM MQ systems.
      • The early code is activated by an IPL, or a by issuing the command REFRESH QMGR TYPE(EARLY), and restarting the queue manager.
   7. Verify correct function before proceeding and review any special actions detailed in the PTFs.
   • If you require fall back at this stage, use normal maintenance procedures to revert to the code for the previous version before PTF application.
4. Update your procedure to start the queue manager.
   • Change the STEPLIB for the queue manager to reference the libraries of the new version of the product.
   • See Task 6: Create procedures for the IBM MQ queue manager.
   • IBM MQ 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 2GB. 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, you 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
   

   • MEMLIMIT defines memory available above the bar; see Address space storage for more information.
   • For specific information on setting MEMLIMIT, when using the accounting and statistics changes in IBM MQ 8.0, see Channel initiator storage usage.
5. Update your procedures for the channel initiator.
   • Change the STEPLIB for the channel initiator to reference the libraries of the new version of the product.
   • See Task 7: Create procedures for the channel initiator.
6. Review any automated alerts when queue manager and channel initiator messages, and errors, are detected.
   New messages might have been added that cause automated alerts, and some messages might have changed.
7. Review C language channel exits
   • Ensure your C language channel exits are using the following statement:

   
   #pragma environment(function-name)
   

   • as defined in the C systems programming environment for system exits, described in the z/OS C/C++ Programming Guide.
8. Update the IBM MQ Db2 configuration.
   • If you are using queue-sharing groups, you must update the procedures.
   • Customize and run the CSQ4570T and CSQ4571T sample JCL in hlq.SCSQPROC.
   • 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.
   • 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 Task 9: Select and set up your coupling facility offload storage environment.
9. Review your security controls for queue-sharing groups, the channel initiator, and all queue managers accessing the coupling facility list structures.
   • See Task 11: Implement your ESM security controls.

   You must ensure that you have addressed the following points when you migrate your security profiles to the latest version of IBM MQ.

   • The External Security Manager software is at the correct version and level and that all of your prerequisite software is installed.
   • IBM MQ security classes have been updated to include the mixed case classes.
   • Enterprise has migrated to mixed case security; see z/OS Migrating a queue manager to mixed case security.
10. Change SYS1.PARMLIB to ensure that any changes you made dynamically remain in effect after an IPL.
    • SYS1.PARMLIB must reference the initialization input data sets that you customize in step 11.
    • See Task 12: Update SYS1.PARMLIB members.
11. 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 Task 13: Customize the initialization input data sets.
    • The CSQINP1 and CSQINP2 initialization input data sets include more samples and the contents of some samples have been moved to other samples. Particular changes to take note of are the commands to define queues to hold publish/subscribe state information. The commands must be in the right order.
    • You must review the customization you have made previously to CSQINP1 and CSQINP2, and merge them into the initial definitions provided with the latest version of the product.
    • Secure the server-connection channels used by clients; see Securing remote connectivity to the queue manager.
    • 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.
12. Update your system parameter module.
    • Your system parameter module is based on the default module, CSQZPARM and CSQ4ZPRM.
    • See Task 17: Tailor your system parameter module.
    • Set the value of the OPMODE parameter in the CSQ6SYSP macro to (COMPAT, 800). The parameters (COMPAT, 800) force a check that the queue manager is started at the 800 command level, and is started in compatibility mode.
13. Update the libraries you added to STEPLIB concatenations to make Batch, TSO, and RRS adapters available to applications.
    • Change the STEPLIB for the Batch, TSO, and RRS adapters to reference the libraries of the new version of the product.
    • See Task 19: Set up Batch, TSO, and RRS adapters.

    Note: You can connect applications that reference the latest version STEPLIB to a queue manager that is running on the latest version, or an earlier version. You must not connect applications that reference a STEPLIB from an earlier version to a queue manager running on a later version.
14. 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.

    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

15. Update the libraries you use to set up the operations and control panels.
    • Change the STEPLIB for the operations and control panel.
    • See Task 20: Set up the operations and control panels.

    Note: You can connect the operations and control panel that references the latest version STEPLIB to the queue manager that is running on the latest version, or an earlier version. You must not connect the operations and control panel that references a STEPLIB from an earlier version to a queue manager running on a later version.
16. Update system libraries to format IBM MQ dumps using the Interactive Problem Control System (IPCS).
    • See Task 21: Include the WebSphere®(r) MQ dump formatting member.