+

Search Tips | Advanced Search

Migrating on UNIX and Linux: single-stage

Single-stage migration is the term used to describe replacing the only installation of IBM 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, Fix Pack 6, single-stage was the only migration scenario. Single-stage migration preserves existing scripts and procedures for running IBM MQ the most. With other migration scenarios you might change some scripts and procedures, but we can reduce the effect queue manager migration has on users.


Before you begin

Attention: From IBM MQ Version 9.0, the ccsid_part2.tbl file replaces the existing ccsid.tbl file, used in previous versions of the product, to supply additional CCSID information. The ccsid_part2.tbl file takes precedence over the ccsid.tbl file and:

The ccsid_part2.tbl is applicable to the following platforms only:

If we have added any of your own CCSID information into your existing ccsid.tbl file, you should copy this information into the new ccsid_part2.tbl file, if you want to take advantage of the new formats in your customizations

You should copy the required information, rather than move the information, so that your existing version of IBM MQ continues to work.


In the single-stage migration scenario, the installation of the later version of the product replaces an earlier version in the same installation location. It is the same migration process that you might have previously used to upgrade the product prior to IBM WebSphere MQ Version 7.0.1, Fix Pack 6. From Version 7.0.1, Fix Pack 6, this method of migration is 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 later version, automatically. Queue managers are automatically associated with the installation on the later 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 later version to be the primary installation, commands such as strmqm work without providing an explicit path to the command.

We can also migrate a queue manager to a later version of the product on a system where an earlier version has been uninstalled. In this case, the queue manager data must have been retained, or restored from a backup.


Procedure

  1. Stop local IBM MQ applications.
  2. Stop all the queue managers and listeners.
  3. Uninstall any fix packs we have installed from the previous IBM MQ version.
  4. Upgrade the earlier version of the product to the later version in the same installation directory.

    • A reason for installing into the same location is to simplify application migration. If you change the installation location, you might remove IBM 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 MQ build scripts for UNIX and Linux. After installation of the later version, the load libraries of the later version of IBM 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 later 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. Upgrade the earlier version of the product to the later version in place, or uninstall the earlier version, without deleting any queue managers, and install the later version in the same default location. Whether we have to uninstall your previous version of the product depends upon your operating system. On the following platforms, we do not have to uninstall a previous version of the product:

      • AIX
      • IBM i, where the process is known as a slip installation

      If mqm.xr.clients and mqm.txclient.rte file sets from earlier versions are installed, you must uninstall these file sets from the earlier versions.

      On the following platforms, you must uninstall the previous version of the product:

      • HP-UX
      • Linux
      • Solaris
  5. Optional: Make the later version of the installation the primary installation.
    1. Run the setmqinst command 
      Inst_1_INSTALLATION_PATH/bin/setmqinst -i -n Inst_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 1 . /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 later 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.
  6. 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 Version 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 the product, you must use setmqm to associate the queue managers with the new installation manually.
    2. Run the strmqm command to start the queue managers and migrate them to the later version of the product. 
      strmqm QM1
strmqm QM2

      At this point, queue manager data is migrated and we 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.


What to do next

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

1