UNIX, Linux, and Windows: Side-by-side migration to a later version

Side-by-side migration is the term used to describe installing a new version of IBM® WebSphere® MQ alongside an older version on the same server. Queue managers remain running during the installation and verification of the new version of IBM WebSphere MQ. They remain associated with the older version of IBM WebSphere MQ. When you decide to migrate queue managers to the new version of IBM WebSphere MQ, you stop all queue managers, uninstall the old version , and migrate them all to the new version of IBM WebSphere MQ.

Before you begin

If you are using IBM WebSphere MQ Version 7.0.1, you must ensure that you are running IBM WebSphere MQ Version 7.0.1.6 before installing the latest version of the product on the same server. Go to Fix Central to obtain the fix pack.

This scenario is one of three, which describe alternative ways to upgrade queue managers from an earlier version of the product. The other scenarios are as follows:

Replace the earlier version with the latest version; see UNIX, Linux, and Windows: Single-stage migration to a later version.
Run the latest version of the product alongside an earlier version ; see UNIX, Linux, and Windows: Multi-stage migration to a later version.

Read these three tasks to plan how you are going to migrate to the multi-installation environment of the latest version. The step-by-step migration scenario sits half-way between the single-stage and multi-stage migration scenarios.

These topics are for planning multi-installation migration. The planning topics guide you in deciding what other tasks you must perform to migrate queue managers and applications to the latest version. For the precise sequence of commands to upgrade a queue manager to the latest version, do the migration task for the platform you are interested in. All the tasks are listed by platform in the links at the end of this topic. As part of the queue manager migration task, back up your existing queue manager data. Even on a multi-installation server, queue managers cannot be restored to a previous command level after migration.

About this task

In the side-by-side migration scenario, you install the latest version of IBM WebSphere MQ alongside queue managers that continue to be associated with Version 7.0.1, or later.

When you are ready to migrate the queue managers, and applications, to the latest version:

Stop all the queue managers.
Uninstall the earlier version of the product.
Migrate all the queue managers and applications to the latest version.

The side-by-side migration scenario is less flexible than multi-stage migration, and might not seem to have any advantages over it. However, side-by-side migration does have advantages over the multi-stage and single-stage approaches. With the side-by-side approach, because you uninstall the earlier version before starting any queue managers, you can assign an installation on the latest version to be the primary installation.

In the multi-stage approach, you cannot set an installation of the latest version to be the primary installation while you continue to run the earlier version.

Having the latest version installation as the primary installation has two benefits.

With the latest version having the primary installation, many applications restart without reconfiguring their environment.
IBM WebSphere MQ commands run against the primary installation, work without providing a local search path.

The advantage the side-by-side scenario has over the single-stage scenario is that you can install and verify the installation of the latest version of the product on the server before switching over to it.

The description of the migration scenario starts with the example in Figure 1.

WebSphere MQ Version 7.0.1 installed in default location, associated with two queue managers, QM1 and QM2, running version 7.0.1, and two applications, 1 connected to QM1, and 2 connected to QM2. — Figure 1. Existing Version 7.0.1 server

Four types of object are important to consider during migration: installations, queue managers, administrative procedures, and applications. The diagram shows the installation an application loads IBM WebSphere MQ libraries from, connections between applications and queue managers, and associations between queue managers and installations. Administrative procedures are omitted from the diagram. Administrative procedures contain IBM WebSphere MQ commands, and scripts that use commands.

Loading from 7.0.1 in Figure 1, refers to the IBM WebSphere MQ installation from which the application loads the IBM WebSphere MQ library it requires; see Loading IBM WebSphere MQ libraries. The connection is a call to MQCONN or MQCONNX, and has not changed from the earlier version of the product to the latest version. The association is the installation that the queue manager is associated with. The association is created either by running the setmqm command, or by starting a queue manager on the earlier version; see Associating a queue manager with an installation.

To run a command, the operating system must find the command in a IBM WebSphere MQ installation. For some commands, you must run the command from the installation that is associated with the correct queue manager. IBM WebSphere MQ does not switch commands to the correct installation. For other commands, such as setmqinst, you can run the command from any installation that has the latest version of the product installed.

If an earlier version of the product is installed, the command that is run is the command for that version, unless the search path is overridden by a local setting. You can override the search path by running setmqenv. If Version 7.0.1 is not installed, you must set the correct path to run a command. If you have set a primary installation, the command that is run is the copy in the primary installation, unless you override the selection with a local search path.

Procedure

Install the latest version in a different installation directory from the earlier version and verify the installation; see Figure 2.
1. Decide on an installation naming convention. Give the installation a name of your choosing, or accept the default installation name.
  For the first installation, the default name is Installation1. For the second installation, the name is Installation2, and so on.
2. Verify the installation.
  Run the installation verification procedures and your own tests.
Figure 2. Install the latest version in a different directory
Uninstall the earlier version of the product; see Figure 3.
- When uninstalling the earlier product, you must stop all queue managers and applications that have loaded a IBM WebSphere MQ library on the server. For this reason, you might choose to postpone uninstalling the earlier version of the product until a convenient maintenance window. When an earlier version of the product is not installed on a server, it is sufficient to stop the queue managers and applications that have loaded libraries from the installation that you are uninstalling or updating. It is not necessary to stop applications and queue managers associated with other installations.
1. Stop all applications that have loaded IBM WebSphere MQ libraries on the server.
2. Stop the queue managers and listeners on the server.
3. Uninstall the earlier version of the product.
Figure 3. Uninstall an earlier version of the product
Make the latest version of the installation the primary installation; see Figure 4.
1. Run the setmqinst command
  On Windows
  "Inst_1_INSTALLATION_PATH\bin\setmqinst" -i -n Inst_1
  On UNIX
  Inst_1_INSTALLATION_PATH/bin/setmqinst -i -n Inst_1
Figure 4. Prepare the installation and applications
- Make the installation primary to avoid specifying a search path to run IBM WebSphere MQ commands.
- If there is a primary installation, UNIX and Linux® applications that expect to find the IBM WebSphere MQ library in /usr/lib, find a symbolic link to the library in /usr/lib/32¹. /usr/lib/32 is normally in the default search path. It is also specified as a load path in the IBM WebSphere MQ build scripts for UNIX and Linux.
- It is sufficient to link applications only to /usr/lib. With a primary installation of the latest version of the product defined on the server, an application can connect to any queue manager associated with any installation on the server. IBM WebSphere MQ loads the correct library for the application.
Start the queue managers and applications; see Figure 5.
1. Optional: Run the setmqm command to associate the queue managers with Inst_1.
```
setmqm -m QM1 -n Inst_1
setmqm -m QM2 -n Inst_1
```
  Running setmqm to associate the queue managers with Inst_1 is optional, because these queue managers are being started on the latest version of the product for the first time.
  
  If you have multiple installations, note that queue managers that were configured to start automatically, and remain after uninstalling IBM WebSphere MQ Version 7.0.1, automatically start under any other existing Version 7.1 (or laer) installation when either the machine reboots, or the Service for that installation is restarted. In order to avoid this, ensure that all queue managers have been moved to the desired installation before uninstalling IBM WebSphere MQ Version 7.0.1.
2. Run the strmqm command to start the queue managers and migrate them to the latest version of the product.
```
strmqm QM1
strmqm QM2
```
Figure 5. Restart the queue managers and applications
- When an application connects to a queue manager, the operating system searches its load path to load the IBM WebSphere MQ library². A Version 7.5, or later, library contains code that checks that the queue manager is associated with an installation. If a queue manager is associated with a different installation, IBM WebSphere MQ loads the correct IBM WebSphere MQ library for the installation the queue manager is associated with.

What to do next

You cannot reinstall an earlier version of the product on a system that has the latest, or any other, version of IBM WebSphere MQ installed.

¹ /usr/lib for 64 bit applications.

² On Windows, the IBM WebSphere MQ library is a DLL. A DLL is sometimes called a load library or a shared library. The entry points to a DLL are defined in a link library, with the file extension .lib32 or .lib. The .lib library is linked at build-time and the DLL loaded at runtime.