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® 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 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.

1. Stop local IBM MQ applications.
2. Stop all the queue managers and listeners.
   This scenario uses two queue managers QM1 and QM2.
3. Uninstall any fix packs you have installed from the previous IBM MQ version.
4. Upgrade the earlier version of the product to the latest version in the same installation directory.
   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 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 the following platforms, you do not have to uninstall a previous version of the product:

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

      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 have to uninstall the previous version of the product:

      • HP-UX
      • Linux®
      • Solaris
   • 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 latest version, the load libraries of the latest 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 latest version.
5. Optional: 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.
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 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.