+

Search Tips | Advanced Search

Migrating on Windows: single stage

Single-stage migration is the term used to describe replacing the only installation of IBM MQ on a server, with a later version of the product. 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

These topics guide you in deciding what other tasks you must perform to migrate queue managers and applications to the later version. For the precise sequence of commands to upgrade a queue manager to the later 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. 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 previously have 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.

When you upgrade the earlier version to the later version, all the objects that you previously created are maintained. The components that were previously installed are preselected in the feature options when you install the new level. If you leave these components selected, we can keep them or reinstall them. If you clear any of these components, the installation process uninstalls them. By default, a typical migration installs only the same features that were installed in the previous version installation.

For example, if IBM MQ Explorer was not installed in an earlier installation, it is not stored in a later installation. If you want IBM MQ Explorer, select a custom installation, and select the IBM MQ Explorer feature on the Features panel. If we do not want IBM MQ Explorer, uninstall the IBM MQ Explorer feature by selecting a custom installation. Then clear the IBM MQ Explorer feature on the Features panel. For more information about how to uninstall features, see Modifying the installation using IBM MQ Installation Launchpad.

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. Log in as a user in group mqm.
  2. Stop all applications using the IBM MQ installation.

    If we use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished all of the file transfers that they were engaged in. There should be no incomplete transfers associated with the agents, and their SYSTEM.FTE.STATE queues should contain no messages.

  3. End all the activity of queue managers associated with the IBM MQ installation.
    1. Run the dspmq command to list the state of all the queue managers on the system.

      Run either of the following commands from the installation that you are updating: 

      dspmq -o installation -o status
dspmq -a

      dspmq -o installation -o status displays the installation name and status of queue managers associated with all installations of IBM MQ.

      dspmq -a displays the status of active queue managers associated with the installation from which the command is run.

    2. Use the MQSC command DISPLAY LSSTATUS to list the status of listeners associated with a queue manager, as shown in the following example: 
      echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName
    3. Run the endmqm command to stop each running queue manager associated with this installation.

      endmqm -c-w-i-p

    5. QmgrName

    9. The endmqm command informs an application that the queue manager it is connected to is stopping; see Stop a queue manager.

      For the maintenance to proceed, applications must respond to an endmqm command by disconnecting from the queue manager and releasing any IBM MQ libraries they have loaded. If they do not, you must find another way to force applications to release IBM MQ resources, such as by stopping the applications.

      You must also stop applications that are using the client libraries that are part of the installation. Client applications might be connected to a different queue manager, running a different installation of IBM MQ. The application is not informed about queue managers in the current installation being shut down.

      Any applications that continue to have IBM MQ shared libraries from the installation loaded prevent you applying IBM MQ maintenance. An application might disconnect from a queue manager, or be forcibly disconnected, but keep an IBM MQ shared library loaded.

      Note: Apply maintenance level updates to multi-instance queue managers on Windows describes how to apply maintenance to a multi-instance queue manager. A multi-instance queue manager can continue to run on one server, while maintenance is applied to another server.
    10. Stop any listeners associated with the queue managers, using the command: 
      endmqlsr -m QMgrName
  4. Back up the queue manager. Take copies of all the queue manager's data and log file directories, including all subdirectories, and also the qm.ini file and the registry entries. For more information, see Backing up and restoring IBM MQ queue manager data.
  5. Stop the IBM WebSphere MQ or IBM MQ Service and exit the Service icon application.
  6. Optional: If you are migrating from IBM WebSphere MQ Version 7.0.1, Fix Pack 6 or later, optionally uninstall the current version of the product.
  7. 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.
    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 later version in place, or uninstall the earlier version, without deleting any queue managers, and install the later version in the same default location. On Windows, we can do this either by using the Installation Launchpad or by using the msiexec command. For more information, see:

      On Windows, uninstalling the previous version of the product before you install the later version is optional.
  8. Reenter domain, user ID, and password information

    When the installation of the latest version completes, the Prepare IBM MQ Wizard starts automatically.

    Where UAC is enabled: If you rerun the Prepare IBM MQ Wizard, ensure that the wizard is run with Administrator privilege, otherwise the wizard might fail.
  9. 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

  10. Start the queue managers and applications.
    1. 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.

      If we 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 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 required 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 later version of the product. 
      strmqm QM1
strmqm QM2

      You must start IBM MQ before you start any listeners.

      When you first start a queue manager after migration:

      • Any new attributes for existing objects are set to their default values.
      • Any new default objects are created.
      • Queue manager data is migrated.
      At this point, when the queue manager data is migrated, we cannot revert to a previous release. Important: Do not use the -c option to start the queue manager, unless you explicitly want to reset or re-create the default system objects.

    • When an application connects to a queue manager, the operating system searches its load path to load the IBM MQ library 1 . 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 On Windows, the IBM 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