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® MQ alongside an older version on the same server. Queue managers remain running during the installation and verification of the new version of IBM MQ. They remain associated with the older version of IBM MQ. When you decide to migrate queue managers to the new version of IBM MQ, you stop all queue managers, uninstall the old version, and migrate them all to the new version of IBM MQ.

Before you begin

If you are using IBM WebSphere® MQ 7.0.1, you must ensure that you are running IBM WebSphere MQ 7.0.1, Fix Pack 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 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 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.

Four types of object are important to consider during migration:

Installations
Queue managers
Administrative procedures
Applications

Administrative procedures contain IBM MQ commands, and scripts that use commands.

To run a command, the operating system must find the command in an IBM MQ installation. For some commands, you must run the command from the installation that is associated with the correct queue manager. IBM 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.
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.
  On AIX® there is no option to set the installation name, Installation1 is set by default.
2. Verify the installation.
  
  Run the installation verification procedures and your own tests.
Uninstall the earlier version of the product.
- When uninstalling the earlier product, you must stop all queue managers and applications that have loaded an IBM 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 MQ libraries on the server.
2. Stop the queue managers and listeners on the server.
3. Uninstall the earlier version of the product.
  - Stop all local IBM MQ applications
  - If you are migrating from IBM WebSphere MQ 7.0.1, stop all your queue managers and listeners, ensuring that you do not delete the queue managers.
    Note: If you are migrating from a release other than IBM WebSphere MQ 7.0.1 you do not need to stop all the queue managers at this point.
Make the latest version of the installation the primary installation.
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
  
  Note: Use the dspmqinst command to discover the <Installation name>, or use the default value <Installation 1>.
- Make the installation primary to avoid specifying a search path to run IBM MQ commands.
- If there is a primary installation, UNIX and Linux® applications that expect to find the IBM 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 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 MQ loads the correct library for the application.
Use the dspmqinst command to discover the <Installation name>, or use the default value <Installation 1>.

Doing this means that you do not have to specify a search path on IBM MQ commands.
Start the queue managers and applications.
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
```
  Notes:
  
  The setmqm step is optional only in the case where migration is from IBM WebSphere MQ 7.0.1 to a later release. In this case, the strmqm command automatically associates the queue manager with its own installation.
  
  If you are migrating between any other releases of IBM MQ, you must use setmqm to associate the queue managers with the new installation manually.
  If you have multiple installations, note that queue managers that were configured to start automatically, and remain after uninstalling IBM WebSphere MQ 7.0.1, automatically start under any other existing Version 7.1 (or later) 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 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
```
  At this point, queue manager data is migrated and you cannot revert to a previous release.
- When an application connects to a queue manager, the operating system searches its load path to load the IBM MQ library ² . A Version 7.1, 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 MQ loads the correct IBM MQ library for the installation the queue manager is associated with.
During this process you continue to use queue manager QM2 while you upgrade queue manager QM1 and you use queue manager QM1 while you upgrade QM2.

Note that each queue manager needs to be stopped in order to be associated with the new installation.

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 MQ installed.

¹ /usr/lib for 64 bit applications.

² On Windows, the IBM 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.