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

Resolving The Problem

Limitations and Restrictions
General Limitations

• Version 7.0.1 introduces a migration switch. Configured by a change to ZPARMs via the OPMODE parameter of CSQ6SYSP, the migration switch supports backward migration by preventing use of certain new functions. While OPMODE is set to COMPAT, it is possible to backward migrate, though certain new functions are not available. Once OPMODE is set to NEWFUNC, all new functions are available, but it is no longer possible to perform backward migration.
• You cannot backward migrate a queue manager, newly created at Version 7.0.1, to a prior release.
• Certain connection types (IMS, batch and RRSBATCH used by WAS and DB2 stored procedures) allow an application to connect to multiple queue managers concurrently. If required, these queue managers can be running different levels of MQ code. In such a scenario, the adapter code (usually referenced via a STEPLIB DD statement or environment variable) must be running from the highest level of the queue managers connected. This ability for the adapter code to support connections to older queue managers means that in a backward migration scenario it is possible to just restart the queue manager and MSTR and CHIN procedures with the back level code and not change connecting jobs.

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:

• Durable Subscriptions stored on SYSTEM.DURABLE.SUBSCRIBER.QUEUE which is cleared by the backward migration process.
• Retained publications stored on SYSTEM.RETAINED.PUB.QUEUE which is cleared by the backward migration process.

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:

• Durable Subscriptions stored on SYSTEM.DURABLE.SUBSCRIBER.QUEUE which is cleared by the backward migration process.
• Retained publications stored on SYSTEM.RETAINED.PUB.QUEUE which is cleared by the backward migration process.

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):

• New message CSQR034I will be issued when backward migration is detected.
• Any CLUSTER TOPIC records found during version 6 restart will be removed from the SYSTEM.CLUSTER.REPOSITORY.QUEUE.
• Any commands relating to clustered topics found on the SYSTEM.CLUSTER.COMMAND.QUEUE will be silently ignored and removed from the queue.
• AUTHINFO AUTHTYPE(OCSP) objects will not be visible at V6, but will reappear (unless they have been deleted at V6) if the queue manager is subsequently restarted at 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.
• After a forwards migration path from V700 to V701, it will NOT be possible to backwards migrate to V6 DIRECTLY (regardless as to whether or not the new functions in V701 have, or have not, been activated). Backwards migration to V700 would have to occur FIRST. Direct migration back to V6 after a V700 to V701 forwards migration will result in abnormal termination of the queue manager with reason code 00C90D01.
• TOPIC objects will not be visible at V6, but will reappear if the queue manager is subsequently restarted at V7
• QALIAS objects with TARGTYPE(TOPIC) will be deleted by the backward migration process. New message CSQI968I will be issued for each such QALIAS deleted by backward migration.
• Any messages MQPUT at V7 are stored in a new format containing message properties. The backward migration process will attempt to convert these into a format readable by version 6.
• New messages CSQR965I, CSQI966I and CSQI967I will be issued for each pageset which contains version 7 format messages indicating the success or failure of this backward migration process.
• The message conversion process is only possible if there are no indoubt units of work during restart after reverting to version 6. If indoubt units of work are found at restart message CSQR020I will provide information, and you will be prompted by message CSQR021D to commit indoubt units of work. If you choose not to commit indoubt units of work, version 6 queue manager startup will be terminated with new reason code 00D99104.
• Any message properties will be placed in an MQRFH2 structure compatible with version 6 JMS applications.
• In the event of failure, CSQI966I is issued, and that pageset is left offline at version 6.
• Conversion of the pageset will be terminated, message CSQI966I issued, and the pageset will be left offline at V6 if the message conversion process fails.
• The message conversion process will fail for :
1. MQPUT at V7 and containing floating point properties when the property has been the subject of a subscriber's selection string. or,
2. MQPUT at V7 with properties provided from an MQSETMP API with a CCSID not supported in an MQRFH2 header at V6.
• New object attributes introduced in version 7 will not be present in version 6, and when you subsequently migrate to version 7 they will be reset to default values.
• If the queue manager is a cluster repository queue manager, then after backward migration, any other version 7 queue managers in the cluster will not receive information about new or changed cluster topics or version 7 attributes on clustered queues and queue managers from this full repository.
• Clustered Alias Queues of TARGTYPE(TOPIC) will be restored to the cache even though the underlying object will have been removed by the data manager. The effect of this is that a queue manager may forward messages to a remote QM which have no meaningful destination on arrival. This is a limitation and should be avoided by deleting any such aliases prior to backwards migration, otherwise these messages will either be placed on the dead letter queue where available, or cause the cluster channel to back out and stop processing.
• If you are using the MQ Explorer to administer your queue manager then after migration between releases the following Explorer actions must be performed:
1. Remove the migrated z/OS queue manager (From the V6 Explorer, the queue manager must be hidden before it can be removed)
2. Add Remote Queue Manager
3. These actions ensure that the Explorer's cached view of queue manager attributes, including the command level are correctly refreshed after the migration.
• If you are going to subsequently migrate back to a release prior to version 6, the channel initiator must be started at version 6 after migrating back from version 7.
• When backward migrating from version 7.0.1 to version 6 an attempt to use a namelist containing both AUTHTYPE(OCSP) and AUTHTYPE(CRLLDAP) AUTHINFO objects in the queue manager SSLCRLNL definition results in SSL channels failing to start with CSQX646E Error accessing LDAP server for channel xxxx

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