Migrating WebSphere MQ queue manager clusters from WebSphere MQ V6 to V7

This article describes best practices for migrating WebSphere MQ queue manager clusters from V6 to V7 on both System z and on distributed operating systems. Topics include minimising application outages, verifying migration success, and taking advantage of new features such as publish/subscribe within clusters through the use of clustered topic objects.


Anthony Beardsmore (abeards@uk.ibm.com), Software Engineer, WebSphere MQ Development, IBM

Anthony Beardsmore is a Software Engineer on the WebSphere MQ Development team at the IBM Hursley Software Lab in the UK. He has worked in that team for the past three years and has given presentations at technical conferences on a variety of WebSphere MQ topics in the United States and Europe. You can contact Anthony at abeards@uk.ibm.com.

13 October 2009

Also available in Chinese


IBM® WebSphere® V7 introduces many new features, including improvements to WebSphere MQ queue manager clustering. Most notable is support for publish/subscribe within clusters through the use of clustered topic objects. WebSphere MQ documentation explains how to migrate individual queue managers to WebSphere MQ V7, but system administrators and architects who use clustering need to understand issues relating to migrating a cluster as a whole, including:

  • Minimising application outages
  • Measuring and verifying migration success and planning for backward migration in the event of migration problems
  • Taking advantage of new WebSphere MQ features
  • Managing the migration of a cluster within the context of the wider WebSphere MQ network and the overall system architecture

This article shows you how to migrate a cluster of queue managers from WebSphere MQ V6.0 to WebSphere MQ V7.0 or V7.0.1, but the information is applicable regardless of the WebSphere MQ version. This article is an update to the article Migrating WebSphere MQ queue manager clusters to WebSphere MQ V6, which is a good place to start for advice on migrating from WebSphere MQ V5.3 to V6.

Migrating queue managers is generally a simple process, because WebSphere MQ is designed to automatically migrate objects and messages, and support mixed version clusters. However, when planning the migration of a cluster, you need to consider a number of issues, which are described below:

Forward migration

Forward migration involves upgrading an existing queue manager to a later version (such as WebSphere MQ V6.0 to WebSphere MQ V7.0) and is supported on all platforms. You may wish to forward migrate in order to take advantage of new features or because the old version is nearing its end-of-service date.

The control blocks that represent cluster objects can change from one version of WebSphere MQ to another, so when a cluster queue manager is started using the new version for the first time, the objects on the SYSTEM.CLUSTER.REPOSITORY.QUEUE are converted by the repository manager process. In the case of z/OS, this process is part of the channel initiator address space, so this conversion takes place when the queue manager's associated channel initiator is started. Once a queue manager has been forward migrated, all objects and persistent messages owned by the queue manager will still be available, and existing applications should continue to work without the need to rebuild them. Objects or attributes relating to features in the new version will be set to default values that ensure minimal changes in behaviour.

Backward migration

Backward migration is the process of downgrading the version of WebSphere MQ used by an existing queue manager, and you may need to use it if you encounter problems after a forward migration. To return to a queue manager on a non-z/OS platform, a backup (taken when the queue manager was running at that version) must be restored, so only objects and messages stored in the backup will be available. After reverting to a backup in this manner, remember to issue a REFRESH CLUSTER command on the restored queue manager to ensure that it has up-to-date information about the cluster.

On z/OS, with appropriate maintenance, WebSphere MQ is designed to backward migrate objects, so a backup is not required (although it is still good practice to take one). When starting a z/OS channel initiator for the first time at the back-level version (with the backward migration PTF applied), repository manager will convert cluster objects on the SYSTEM.CLUSTER.REPOSITORY.QUEUE. After a z/OS queue manager has been backward migrated, all objects and attributes supported by the back-level version will be available, as will persistent messages. Objects or attributes relating only to the new version will be lost after a backward migration, and therefore you should not backward migrate after running the new version for an extended period.


It is important when making any system changes to test the changes in a test or QA environment before rolling out the changes in production, especially when migrating software from one version to another. Ideally, an identical migration plan is executed in both test and production to maximise the chance of finding potential problems in test rather than in production. In practice, test and production environments are unlikely to be architected or configured identically or to have the same workloads, so it is unlikely that the test migration steps will exactly match the production steps. Whether or not the plans and environments for test and production differ, it is always possible to find problems when migrating the production cluster queue managers. Techniques for minimising planned and unplanned outages in a migration scenario are described in the sections below.

Migration and backout plans

When creating the migration plan, you need to consider general queue manager migration issues, clustering specifics, wider system architecture, and change control policies. Document and test the plan before migrating production queue managers. For a detailed example, see Migrating one cluster queue manager in the WebSphere MQ V7 information center.

Administrators who are confident in the migration process may want to simplify the process by removing the steps to suspend and resume the queue manager. Conversely, administrators who are less confident in the migration process may want to remove queue the manager from the cluster before migrating.

A backout plan should be documented before migrating. It should detail what constitutes a successful migration, the conditions that trigger the backout procedure, and the backout procedure itself. The procedure could involve removing or suspending the queue manager from the cluster, backwards migrating, or keeping the queue manager offline until an external issue is resolved.

Alternate destinations

Applications can take advantage of the workload balancing features of clustering to reduce the risk of outages caused by queue manager downtime. Outages can be planned (such as migrating a queue manager) or unplanned (such as a disk failure). If a queue manager is the only host for a particular cluster queue, stopping that queue manager can obviously cause application outages. You can avoid these outages by defining the queue on other queue managers in the cluster, so that whilst migrating one queue manager, applications can use the alternate queues. Using multiple queues in this manner does not help if applications have affinities with a particular queue. Two common reasons for affinities are that queues are opened bind on open, or that the queue manager name has been specified on MQOPEN calls. You need to be aware of affinities during normal operations and even more so during migration, when the risk of extended queue manager downtime is increased.

Synchronising migration with application downtime

If there are no alternate destinations available, you can minimise downtime by synchronising queue manager migration with application downtime. Ideally, the cluster queue manager will also be tested before bringing applications back online. In a cluster, it can be difficult to detect if remote applications are using local cluster queues, so careful monitoring of queues and channels may be required.

Staged migrations

When migrating a cluster, it is sensible to carry out a staged migration and migrate queue managers one at a time. It is reasonable to leave days between migrating each queue manager in the cluster, in order to test applications before wholly committing all queue managers to run at the new version.

Cluster queue managers are designed to partake in clusters with queue managers running at different versions, which is why a staged a migration is possible. It is advisable, but not required, to migrate full repositories first. If all full repositories are migrated before partial repositories, new features will be exploitable by all queue managers running at the new version. Queue managers at the back-level version cannot use the new features, and will appear in the repositories of new version queue managers with the default values for any new version attributes.

If full repositories are not migrated before partial repositories, then the cluster will continue to work, but not all queue managers will be able to use the new features because of the manner in which cluster objects are published around the cluster, via full repositories, as shown in this example:

Table 1
Queue Manager Name Full or partial repository Cluster queues
QM1Full None
QM2Full None

Start with a cluster of five queue managers as shown in Table 1, with all queue managers running at WebSphere MQ V6.0, and then migrate the partial repositories (QM3, QM4, and QM5) to WebSphere MQ V7. One of the reasons for migrating is to use the new V7.0 feature called asynchronous put, which adds a new property to queues, the Default Put Response (DEFPRESP). To modify this value on the cluster queues above, issue the following command on QM3 and QM4: ALTER QL(Q1) DEFPRESP(ASYNC). When you execute this command, the following updates occur:

  • QM3 and QM4 update the objects’ descriptions on the full repositories.
  • Each full repository updates its local repository, and forwards the original update from QM3 and QM4 to queue managers that have registered interest in Q1.
  • QM5 has registered interest in Q1, as applications connected to QM5 have previously put messages to Q1.

At this point, the full repositories hold QM3's changed cluster queue record, but as the full repositories are running at V6, the record is a V6 record, and therefore does not contain the DEFPRESP attribute.

QM5 holds QM3's changed cluster queue record, which includes the DEFPRESP attribute because QM5 is running at V7.0. Despite QM5 receiving the updated record via the back-level full repositories, it has received the V7.0 attribute data. Full repositories are able to forward object updates, so they can propagate records with attributes that they themselves do not support. Executing DIS QCLUSTER(Q1) DEFPRESP CLUSQMGR on QM5 returns:


This response means that all the partial repositories can be upgraded before the full repositories and still take advantage of new function. The following section shows why you should upgrade full repositories first when possible. Suppose you add a new V7.0 queue manager (QM6) to the cluster and an application connects to it and opens Q1. At this point:

  • QM6 needs to ask the full repositories about Q1 and where it is hosted.
  • The full repositories pass the information they hold for Q1 and the queue managers that host it (QM3 and QM4) to QM6
  • Since the full repositories hold only V6.0 records, the records they send to QM6 do not contain DEFPRESP attributes. The unknown attributes will be substituted with default values on QM6.

Executing DIS QCLUSTER(*) DEFPRESP on QM6 would now return:


QM3's DEFPRESP does not match that on the actual Q1 object (5). This mismatch will be resolved the next time QM3 publishes its cluster receiver, as the full repositories will then forward the object update (including V7.0 attribute data) from QM3 straight on to QM6. Mismatches like this, caused by the back-level full repositories publishing direct from their repositories, can also be caused by opening a queue for the first time or by issuing REFRESH CLUSTER on a partial repository.

Using new WebSphere MQ V7 features

After a queue manager has been migrated, you should verify existing function and applications. After this verification, you can introduce new features to the test and then to the production environment.

WebSphere MQ V7 introduced a new way to exploit clusters for pub/sub messaging. An MQ cluster is designated as a pub/sub cluster when topic objects are defined that specify the cluster’s name in their attributes. Publications on the given topic string anywhere in the cluster are then flowed to any other queue managers with subscribers for that topic, to be delivered locally to applications.

As explained above under "Staged migrations," when using any new feature, it is preferable to have upgraded at least all full repositories to V7. In the case of pub/sub, upgrading enables the repository to understand and retain information about topic objects that they would otherwise pass on but discard. Obviously, any back-level partial repositories will be unable to participate in clustered pub/sub.

Pub/sub clusters have different performance and scaling implications compared to regular point-to-point (queued) clustering. In particular, to share information about subscriptions, all queue managers may need to communicate with all other queue managers in a pub/sub cluster from time to time (implying a large number of active channels). Therefore it is important to consider the effect that these additional channels may have on your systems, and test your topology before defining topics in an existing production cluster:

Example cluster before introduction of clustered topic (arrows indicate that certain channels are active)
Pub sub cluster scalability: before
The same cluster after executing DEFINE TOPIC(SPORTS) TOPICSTR(/sport) CLUSTER(DEMO) on QMgr A (all channel pairs active for a period of time)
Pub sub cluster scalability: after

WMQ V6 applications on platforms other than z/OS may have made use of pub/sub through the queued interface (manual construction of RFH1 or PCF subscription requests and publications). These applications will continue to function as expected on V7.0, and can now also be used on z/OS queue managers. (Some administrative setup may be required to create the streams and topics used by these older applications. See the information center for further details, as this is not a clustering-specific issue.) If you want these applications to participate in a pub/sub cluster, the topic may be made clustered in the same way as described above. Subscribing and publishing applications anywhere in the cluster may interoperate whatever interface to the pub/sub engine is used.

Full repository availability

In general, the availability of full repository queue managers is important because all object publications (due to definition changes or the normal 27-day republish cycle) are sent via the full repositories. If there are no full repositories available, publications cannot be propagated around the cluster. Application traffic over existing cluster channels between partial repositories is not affected by full repository availability. It may be acceptable to have all full repositories unavailable if there are few or no definitional changes occurring during an outage.

During migration, when a queue manager is started at the new version, its local cluster objects are changed, since they now have new attributes. This definition change causes the queue manager to publish the changes to the full repositories. If the full repositories are available, they will publish the records to partial repositories that are subscribed to the changed objects. If the full repositories are not available, other partial repositories will not be informed of the change to the object, but they will still have any existing records for the changed object and therefore continue to function.

This article explained how to deal with some of the major issues involved when migrating cluster queue managers. To minimize the impact of these issues, it is important to invest in pre-migration planning and post-migration testing. WebSphere MQ support of mixed-version clusters, which allow staged migrations, is a powerful asset to companies wishing to move the next version of WebSphere MQ.


The author would like to acknowledge Ian Vanstone as the author of the previous version of this article, and thank Ian as well as colleagues Andrew Banks and Jason Edmeades for their help in reviewing this article.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

ArticleTitle=Migrating WebSphere MQ queue manager clusters from WebSphere MQ V6 to V7