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

Multi-stage migration is the term used to describe running a new version of IBM® WebSphere® 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 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:

  1. Replace the earlier version with the latest version; see UNIX, Linux, and Windows: Single-stage migration to a later version.
  2. 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 Version 7.5. The multi-stage migration scenario is the most flexible approach to migrating from Version 7.0.1 to Version 7.5.

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.5 or later.
  • If you are running the IBM WebSphere MQ .NET monitor in transactional mode, the queue manager it connects to must be the primary installation.
You cannot migrate these applications to Version 7.5 until you uninstall Version 7.0.1.

About this task

In the multi-stage migration scenario, you install IBM WebSphere MQ Version 7.5 alongside running queue managers that continue to be associated with Version 7.0.1. You can create queue managers and run new applications using the IBM WebSphere MQ Version 7.5 installation. When you are ready to start migrating queue managers and applications from Version 7.0.1, you can do so, one-by-one. When migration to Version 7.5 is complete, uninstall Version 7.0.1, and make the Version 7.5 installation primary.

With the multi-stage approach, until you uninstall version 7.0.1, you must configure an environment to run applications that connect to a version 7.1 queue manager. You must also provide a path to run IBM WebSphere MQ commands. Both these tasks are accomplished with the setmqenv command.

Note: When you have uninstalled Version 7.0.1, and set a Version 7.5 installation primary, 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.

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

Figure 1. Existing Version 7.0.1 server
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.

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

  1. Install Version 7.5 in a different installation directory to Version 7.0.1 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 Version 7.5 in a different directory
    WebSphere MQ Version 7.1, Inst_1, installed in a different location, leaving the queue managers and applications connected to 7.0.1 running.
    • You might create new queue managers running Version 7.5, and start to develop new applications before migrating applications from Version 7.0.1.
  2. Configure the operating system so that applications load the Version 7.5 libraries; see Figure 3.
    • Migrate queue managers one at a time. The first set of applications to load the Version 7.5 libraries 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 they load the Version 7.5 libraries, IBM WebSphere MQ automatically loads the Version 7.0.1 libraries for those applications that connect to Version 7.0.1. As the first step, you might 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.
    • Some of the applications might be running as IBM WebSphere MQ MQI client applications on another workstation. When you migrate a queue manager, clients connected to it continue to run without loading a Version 7.5 client library. You can migrate these clients later, when you need to do so.
    • If any IBM WebSphere MQ MQI client applications are using the Version 7.0.1 library on the server, you must eventually migrate the clients to use Version 7.5 libraries, before you uninstall Version 7.0.1.

    To make an application load a Version 7.5 library, you have three choices:

    • Run setmqenv to modify the local path that is searched for IBM WebSphere MQ libraries.
    • Modify the global search path that is searched for IBM WebSphere MQ libraries.
    • Relink applications with an additional runtime load path.
    Figure 3. Application 1 loads IBM WebSphere MQ libraries from Inst_1
    Application 1 loads libraries from installation 1.
    • 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 WebSphere MQ load libraries at the start of the LD_LIBRARY_PATH environment variable, and adds the variable to the local environment; see Loading IBM WebSphere 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.
  3. Restart the queue manager and the applications that connect to it; see Figure 4.
    Figure 4. Restart QM1 and application 1.
    Application connected to QM1 running later version
    1. 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
    2. Run the setmqm command to associate QM1 with Inst_1. 
      setmqm -m QM1 -n Inst_1
    3. Run the strmqm command to start QM1 and migrate it to Version 7.5. 
      strmqm QM1
    4. Restart application 1
      • The application loads the Version 7.5 library and connects to QM1, which is associated with Version 7.5.
  4. Migrate all queue managers and applications to Version 7.5; see Figure 5.
    • Repeat steps 2 and 3, when required, until all the queue managers and applications are migrated to Version 7.5.
    Figure 5. Migrate all queue managers and applications to Version 7.5
    All applications and queue managers running 7.1.
  5. Uninstall Version 7.0.1; see Figure 6.
    • 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 6. Uninstall Version 7.0.1
    WebSphere MQ Version 7.0.1, uninstalled, 7.1 made primary.
  6. Make Inst_1 the primary installation; see Figure 7.
    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
    • You do not have to set up a search path to run IBM WebSphere MQ commands from the primary installation.
    • If you set a Version 7.5 installation 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.
    Figure 7. Make Version 7.5 primary
    WebSphere MQ Version 7.0.1, uninstalled, 7.1 made primary.

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.

Now that you have uninstalled Version 7.0.1, and made a Version 7.5 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 IBM WebSphere MQ libraries. If you have only one Version 7.5 installation it is not necessary to run setmqenv to run commands.