UNIX, Linux, and Windows: Single-stage migration to a later version

Single-stage migration is the term used to describe replacing the only installation of IBM® WebSphere® MQ on a server, with a later release. Single stage migration is also known as upgrading in place or in place upgrade. Until Version 7.0.1.6, single-stage was the only migration scenario. Single-stage migration preserves existing scripts and procedures for running IBM WebSphere MQ the most. With other migration scenarios you might change some scripts and procedures, but you can reduce the effect queue manager migration has on users.

Before you begin

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:

Install the latest version of the product alongside an earlier version ; see UNIX, Linux, and Windows: Side-by-side 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. Even if you do not plan to have more than one version of the installation on a server, read this topic. The steps to upgrade IBM WebSphere MQ from Version 7.0.1 to Version 7.5 have changed.

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 single-stage migration scenario, the installation of the latest version of the product replaces an earlier version in the same installation location. It is the same migration process that you would have used to upgrade the product prior to IBM WebSphere MQ Version 7.0.1.6 . It is now termed single-stage migration, in contrast to side-by-side and multi-stage migration.

The advantage of single-stage migration is that it changes the configuration of a queue manager on the earlier version as little as possible. Existing applications switch from loading the libraries from the earlier version, to loading the libraries of the latest version, automatically.

Queue managers are automatically associated with the installation on the latest version. Administrative scripts and procedures are affected as little as possible by setting the installation to be the primary installation. If you set the installation of the latest version to be the primary installation, commands such as strmqm work without providing an explicit path to the command.

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

Earlier version of the product installed in default location, associated with two queue managers, QM1 and QM2, running that version of the product, and two applications, 1 connected to QM1, and 2 connected to QM2. — Figure 1. Existing server on an earlier version

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

Upgrade the earlier version of the product to the latest version in the same installation directory; 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. Upgrade the earlier version of the product to the latest version in place, or uninstall the earlier version, without deleting any queue managers, and install the latest version in the same default location.
  Whether you have to uninstall your previous version of the product depends upon your operating system.
  On:
  - AIX®
  - Windows
  - IBM i, where the process is known as a slip install
  you do not have to uninstall a previous version of the product.
  On:
  - HP-UX
  - Linux®
  - Solaris
  you have to uninstall the previous version of the product.
Figure 2. Upgrade of earlier version of product to latest version in the default directory
- A reason for installing into the same location is to simplify application migration. If you change the installation location, you might remove IBM WebSphere MQ libraries from an application search path. To migrate an application search path you must modify the application environment, or more rarely, the application itself.
- The default installation path is specified as a load path in the IBM WebSphere MQ build scripts for UNIX and Linux. After installation of the latest version, the load libraries of the latest version of IBM WebSphere MQ are in the same location as were the libraries of the earlier version. If you built applications by following the examples in the product documentation for the earlier version, the applications load the correct libraries in the latest version.
Make the latest version of the installation the primary installation; see Figure 3.
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 3. 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 4.
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 4. 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.