IBM Support

Problems and solutions when migrating to WebSphere MQ for z/OS v7.0.1

Technote (troubleshooting)


Problem(Abstract)

This document discusses considerations and procedures for backward migration, or fallback, of WebSphere MQ for z/OS V7.0.1 to prior releases.

Symptom

Migration and Fallback issues


Environment

The Backward Migration Scenario

After installation of a new release of MQ, it is envisaged that customers will stop the queue manager which is running with the prior release of code and restart using the new release of code. There will then be some period of running usual workload with the new release of MQ, prior to exploitation of new capabilities of MQ provided in the new release.

Customers tell us, that often MQ is upgraded as part of a ServerPac installation, and often many components in the z/OS image are changed at one time.

In the event of any issues arising, standard practice is to backout the most recent maintenance and fallback to the prior release while the issues are investigated and resolved. MQ provides backward migration PTFs on supported earlier releases to support fallback to that earlier release.

Diagnosing the problem

Procedure for Backward Migration

First class migration support is provided for customers migrating from both WebSphere MQ Version 6 and WebSphere MQ Version 7 to WebSphere MQ Version 7.0.1.

The backward migration APAR for WebSphere MQ for z/OS Version 6 is PM39965. PTFs for this APAR must be applied on Version 6 prior to attempting fallback from WebSphere MQ for z/OS Version 7.0.1.

The backward migration APAR for WebSphere MQ for z/OS Version 7 is PK95837. PTFs for this APAR must be applied on Version 7 prior to attempting fallback from WebSphere MQ for z/OS Version 7.0.1.

Please note: For the latest information on migration APARs please refer to WebSphere MQ Support, Migration PTFs

Resolving the problem

Limitations and Restrictions

General Limitations



Backward Migration to Version 7.0.0

The backward migration APAR for WebSphere MQ for z/OS Version 7 is PK95837. PTFs for this APAR must be applied on Version 7 prior to attempting fallback from WebSphere MQ for z/OS Version 7.0.1.

After backward migration to Version 7.0.0, any durable state associated with publish and subscribe (pub/sub) processing is cleared. This state includes:


The queue manager PSMODE attribute is set to DISABLED so that pubsub is not started in a V7.0.0 queue manager after fallback from Version 7.0.1.

When the queue manager is subsequently restarted at Version 7.0.1, if pubsub capability is required it is necessary to set the QMGR PSMODE attribute to ENABLED. If you are using distributed pubsub, then PSMODE should be ENABLED prior to starting the CHINIT - see APAR PM00999 for further details and a solution to this issue.

  • Backward Migration to Version 6.0.0
The backward migration APAR for WebSphere MQ for z/OS Version 6 is PM39965. PTFs for this APAR must be applied on Version 6 prior to attempting fallback from WebSphere MQ for z/OS Version 7.0.1.

Version 6 does not provide pub/sub capability therefore after backward migration any durable state associated with publish and subscribe (pub/sub) processing is cleared. This state includes:


When reverting to Version 6 after running a queue manager at either version 7.0.0 or version 7.0.1 the following should be considered (where a comment references V7, then it is applicable to either V7.0.0 or V7.0.1):
  • It will NOT be possible to backwards migrate to V6 from V701 if the new functions available in V701 have been activated by the new OPMODE parameter. Refer to the "Controlling new functionality and backward migration using the OPMODE property" section of the Migration Manual for more details.
    If version 701 has been started with OPMODE=NEWFUNC then any attempt to restart the queue manager at version 6 will result in abnormal termination of the queue manager with reason code 00C90D01.
  • The message conversion process will fail for :
  • If you are using the MQ Explorer to administer your queue manager then after migration between releases the following Explorer actions must be performed:

Documentation Changes for V6 Backward Migration APAR
The following new message and code descriptions will be added to the WebSphere MQ for z/OS Version 6.0 Messages and Codes manual, GC34-6602-00 :
CSQI967I & Backward migration completed for msgs on pageset &
Explanation:
The indicated page set has had all messages successfully migrated to a format where they can be processed by applications running on an MQ V6 queue manager.

The following limitations apply:
• If SYSTEM.RETAINED.PUB.QUEUE is defined on this page set, all messages on that queue will have been deleted. If the queue manager is subsequently restarted at V7 or V701, then all retained publications are lost.
• If the queue manager is subsequently restarted at V7 or V701, then all retained publications are lost.
• If SYSTEM.DURABLE.SUBSCRIBER.QUEUE is defined on this page set, all messages on that queue will have been deleted. If the queue manager is subsequently restarted at V7 or V701, then all durable subscriptions are lost.
• If the queue manager is subsequently restarted at V7 or V701, then all durable subscriptions are lost.

The following new section is added to the Migration Information Manual for WebSphere MQ Version 7.0.1 :-

Upgrading to WebSphere MQ for z/OS Version 7.0.1

This section describes the things that you must consider if you are migrating a single queue manager from a previous version of WebSphere MQ.

First class migration support is provided to WebSphere MQ for z/OS Version 7.0.1 from either WebSphere MQ for z/OS Version 6.0, or from WebSphere MQ for z/OS Version 7.0. This means you can restart a queue manager at WebSphere MQ Version 7.0.1 by replacing the executable code (for example, the STEPLIB data sets) with equivalent Version 7.0.1 libraries and then restarting the queue manager. After migrating to Version 7.0.1 from Version 6.0, when a backward migration PTF has been applied to Version 6.0 code, it is possible to fall back from Version 7.0.1 operation to Version 6.0. Likewise, after migrating to Version 7.0.1 from Version 7.0, when a backward migration PTF has been applied to Version 7.0 code, it is possible to fall back from Version 7.0.1 operation to Version 7.0.

Service Parameters

In Version 7.0.1 some functions which were enabled using serviceparm in earlier releases are now controlled by other mechanisms. Appropriate configuration changes must be made when migrating backwards or forwards to keep equivalent function.

More granular MULC recording, provided by PM20880 as serviceparm bit '00000000 10' is replaced in V701 by MULCCAPT=REFINED system parameter.


Symptoms associated with common issues

Queue manager terminated at startup with reason code 0C90D01.
During startup it has been detected that there is a mis-match between the level of queue manager code and configuration information held on the pagesets. This suggests either:

● The queue manager is being backward migrated and backward migration PTFs are not installed.

● The queue manager is being backward migrated, but has previously been run in NEWFUNC mode at Version 7.0.1


IMS Adaptor MQCONN failed with completion code 2 and reason code 2129, MQRC_ADAPTER_CONN_LOAD_ERROR.
This return code will be received by an application built with the V7.0.1 CSQQSTUB and run in an IMS region configured to use the V6 or V7.0.0 IMS adapter (i.e. STEPLIB). Either rebind the application with the V7.0.0 stub (this may not be possible if message property APIs are used by the application), or, configure the IMS region to use the V7.0.1 adaptor code.

IMS Adaptor MQRC_GMO_ERROR 2186 or MQRC_PMO_ERROR 2173
These return codes will be received by an application performing MQGET or MQPUT which has been coded to use message property handles, but which is now connected to a version 6 queue manager. Message property function was introduced in MQ Version 7. These applications cannot be run against back level queue managers.


Language Environment Errors
Attempting to run LE applications built with MQ V7.0.1 DLLs in a procedure configured to use a back level MQ adaptor will produce errors attempting to load the missing DLLs during MQCONN processing.

If the DLL cannot be found:

CEE3501S The module <MQ DLL module name> was not found
The MQ DLL module name begins with the characters CSQBLB followed by a suffix which indicates the environment it is providing function for.

When the DLL is successfully loaded, but CSQBSRV loaded from STEPLIB is not at the V7.0.1 level one of the following symptoms may be seen:

● With an MQ Version 6 Adapter (STEPLIB):

CEE3250C The system or user abend S5C6 R=NULL was issued. From entry point introduce_myself at compile unit offset +00000638 at entry offset +00000638 at address xxx

● With an MQ Version 7.0.0 Adapter (STEPLIB):

CEE3250C The system or user abend S5C6 R=00C20001 was issued. From entry point introduce_myself at compile unit offset +00000638 at entry offset +00000638 at address xxx

The reason code of 00C20001 from the Version 7.0.0 adapter correctly identifies that the stub and batch adapter are at incompatible versions.


Message Properties
Version 7 introduced message properties. To enable selection by message properties, messages containing such properties are internally stored in a different format. This means that on backward migration to V6, messages containing message properties have to be reformatted. This process leads to the following effects.

● After migrating back to v6, an MQGET will retrieve a message, but backward migration has converted message properties into an RFH2 header and this is now returned in addition to any payload. The function is as if you specified MQGMO_PROPERTIES_FORCE_MQRFH2 at V7. A JMS application is able to interpret the properties stored in an RFH2 header at V6 as expected.

● If the queue manager is subsequently migrated forward to V7.0.0, the messages are still stored in the V6 format and an MQGET will always get an RFH2 even if MQGMO_PROPERTIES_IN_HANDLE is used. If you ask for a handle MQINQMP reports there are no properties.
An equivalent effect is that the PROPCTL queue attribute also has no effect on how the backward migrated message is seen by an MQGET.

● If, after backward migration to V6, the queue manager is migrated forward to V7.0.1, additional function in V7.0.1 allows an MQGET to retrieve the message properties either in a message handle or in an RFH2.

Referenced Publications:
WebSphere MQ “Migration”
WebSphere MQ “z/OS Messages and Codes”
The latest versions, or an Information Center can be found at http://www.ibm.com/software/integration/wmq/library/crossplatform_books.html

Product Alias/Synonym

WMQ MQ

Document information

More support for: WebSphere MQ
Install / Migration

Software version: 6.0, 7.0, 7.0.1

Operating system(s): z/OS

Reference #: 1408135

Modified date: 01 December 2009