Multi-stage migration is the term used to describe running a new version of IBM® MQ alongside an older version on the same server. After installing the new version alongside the old, you can create new queue managers to verify the new installation, and develop new applications. At the same time, you can migrate queue managers and their associated applications from the old version to the new. By migrating queue managers and applications one-by-one, you can reduce the peak workload on staff managing the migration.
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.
- Install the latest version of the product alongside
an earlier version ; see UNIX, Linux, and Windows: Side-by-side 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 multi-stage
migration scenario is the most flexible approach to migrating from IBM
WebSphere MQ 7.0.1 to the
latest version.
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.
Note:
- If an application uses COM or ActiveX it can connect to any queue manager as long as there is a primary installation and it is Version 7.1 or later.
- If you are running the IBM MQ.NET monitor in transactional mode, the queue manager it connects to must be the primary installation.
You cannot migrate these applications to the latest version until
you uninstall the earlier version.
About this task
In the multi-stage migration scenario, you install the latest version of the product alongside running queue managers that continue to be associated with the earlier version. You can create queue managers and run new applications using the latest version installation. When you are ready to start migrating queue managers and applications from the earlier, you can do so, one-by-one. When migration to the latest version is complete, uninstall the earlier version, and make the latest version installation the primary installation.
With the multi-stage approach, until you uninstall the earlier version , you must configure an environment to run applications that connect to a queue manager to the latest version. You must also provide a path to run IBM MQ commands. Both these tasks are accomplished with the setmqenv command.
Note: When you have uninstalled the earlier version, and set the latest version as a primary installation, in most circumstances it is not necessary to run the setmqenv command to run applications. It is still necessary to run setmqenv to set the environment for commands that connect to a queue manager associated with an installation that is not primary.
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 and verify the installation.
-
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.
-
Verify the installation.
Run the installation verification procedures and your own tests.
- You might create new queue managers running the latest version, and start to develop new applications before migrating applications from the earlier version.
-
Configure the operating system so that applications load the libraries for the latest version
of the product.
-
Migrate queue managers one at a time.
The first set of applications to load the libraries for the latest version of the product are the
applications that connect to the first queue manager you are going to migrate.
It does not matter if those applications also connect to other queue managers on the server. If
the applications load the latest version libraries, IBM MQ automatically loads the libraries for the earlier version for those applications that connect to
that version.
You can either migrate the operating system environment of all applications, or just the
applications that connect to the first queue manager you are going to migrate.
-
Migrate IBM MQ MQI
client applications
Some of the applications might be running as IBM MQ MQI
client applications on another workstation. When you
migrate a queue manager, clients connected to it continue to run without loading a client library
for the latest version.
You can migrate these clients later, when you need to do so.
Important: If any
IBM MQ MQI
client applications are using the library for
the earlier version on the server, you must eventually migrate the clients to use the latest version
of the product before you uninstall the earlier version.
-
Migrate an application to load the new library for the latest version:
- Run setmqenv to modify the local path that is searched for IBM MQ libraries.
- Modify the global search path that is searched for IBM MQ libraries.
- Relink applications with an additional runtime load path.
- Consult operating system documentation about how to modify the global search path, or include a
fixed runtime load path in the application load module.
To run
setmqenv using the
-s option:
Windows:
"Inst_1_INSTALLATION_PATH\bin\setmqenv" -s
The -s option sets up the environment for the installation that runs the
setmqenv command.
UNIX:
.Inst_1_INSTALLATION_PATH/bin/setmqenv -s -k
The -k option inserts the path to the IBM MQ load libraries at the start of the
LD_LIBRARY_PATH
environment variable, and adds the variable to the local
environment; see Loading IBM MQ libraries.
Note: On UNIX the leading
.
is critical. The dot followed by a space instructs the command shell run
setmqenv in the same command shell and inherit the environment set by
setmqenv.
-
Restart the queue manager and the applications that connect to it.
-
Set up the local environment to the installation
Inst_1
.
Windows:
"Inst_1_INSTALLATION_PATH\bin\setmqenv" -s
The -s option sets up the environment for the installation that runs the setmqenv command.
UNIX:
.Inst_1_INSTALLATION_PATH/bin/setmqenv -s
-
Run the setmqm command to associate
QM1
with Inst_1
.
-
Run the strmqm command to start
QM1
and migrate it to the latest version.
-
Restart application
1
- The application loads the latest version library and connects to
QM1
, which is associated with the latest version of the product.
-
Migrate all queue managers and applications to the latest version.
- Repeat steps 2 and 4, when required, until all the queue managers and applications are migrated to the latest version of the product.
-
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.
-
Stop all applications that have loaded IBM MQ libraries on the server.
-
Stop the queue managers and listeners on the server.
-
Uninstall the earlier version of the product.
-
Make
Inst_1
the primary installation.
-
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>
.
- You do not have to set up a search path to run IBM MQ commands from the primary installation.
- If you set an installation of the latest version of the product as primary on UNIX and Linux®, you do not have to set up
LD_LIBRARY_PATH
in most cases. You can remove calls to setmqenv to set LD_LIBRARY_PATH
.
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.
Now that you have uninstalled the earlier version of the product, and made the latest installation primary, you can review how the application runtime environment is set. It is no longer necessary to run setmqenv to set up the search path to load libraries for the latest version. If you have only one installation of the latest version of the product installed, it is not necessary to run setmqenv to run commands.