+

Search Tips | Advanced Search

Migrating a queue manager to a later version on Windows

On Windows platforms, follow these instructions to migrate a queue manager from an earlier version to a later version of IBM MQ .


Before starting

If we have installed early support program code on the server, we must delete all the queue managers created with the installation. Uninstall the code before proceeding with installing the production level code.

  1. Create a migration plan; see Plan to migrate IBM MQ to a later version on Windows.
  2. Review the IBM MQ system requirements for the latest version, including information about the versions of Windows that IBM MQ supports. See System Requirements for IBM MQ.
  3. Back up the system before you install a later version of IBM MQ over an earlier version. Once you have started a queue manager we cannot revert to the previous version. If we must restore the system, we cannot recover any work, such as changes to messages and objects, performed by the later version of IBM MQ. For more information about backing up your system, see Backing up and restoring IBM MQ queue manager data.
  4. Review any other installed SupportPacs for their applicability to the later version.
  5. If we are running on a server with multiple IBM MQ installations, we must identify the installation. Make sure that the commands you enter run against the correct installation; see setmqenv.


To run a command, the operating system must find the command in an IBM MQ installation. For some commands, we 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, we can run the command from any installation that has the later 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. We can override the search path by running setmqenv. If Version 7.0.1 is not installed, we must set the correct path to run a command. If we 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. 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 we 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 QmgrName

      The endmqm command informs an application that the queue manager it is connected to is stopping; see Stopping 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, we must find another way to force applications to release IBM MQ resources, such as by stopping the applications.

      We 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: Applying 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.
    4. 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 we are doing a single stage migration, optionally uninstall the current version of the product. Note, that you carry out this step only if we are doing a single stage migration; see Migrating on Windows: single stage.
  7. Install the later version of IBM MQ. On Windows, we can do this either by using the Installation Launchpad or by using the msiexec command. For more information, see:

  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. Start the queue manager. 
    strmqm QmgrName
    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.

    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.

    We must start IBM MQ before you start any listeners.


What to do next

Complete the tasks in your migration plan, such as verifying the new code level and deploying new functions such as automatically restarting client connections.

If we are using publish/subscribe, we must migrate the publish/subscribe broker.

If the queue manager is a member of a queue manager cluster, migrate the other members of the cluster.

Important: We must migrate the publish/subscribe broker state before we migrate your IBM MQ system to IBM MQ Version 8.0, or later, as broker publish/subscribe migration is not supported in IBM MQ Version 8.0, or later.

  • 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.
  • Migrating on Windows: side-by-side
    Side-by-side migration is the term used to describe installing a later version of IBM MQ alongside an earlier version on the same server. Queue managers remain running during the installation and verification of the later version of IBM MQ. They remain associated with the earlier version of IBM MQ. When you decide to migrate queue managers to the later version of IBM MQ, you stop all queue managers, uninstall the earlier version, and migrate them all to the new version of IBM MQ.
  • Migrating on Windows: multi-stage
    Multi-stage migration is the term used to describe running a later version of IBM MQ alongside an earlier version on the same server. After installing the later version alongside the earlier version, we can create new queue managers to verify the later installation, and develop new applications. At the same time, we can migrate queue managers and their associated applications from the earlier version to the later version. By migrating queue managers and applications one-by-one, we can reduce the peak workload on staff managing the migration.

Parent topic: Migrating a queue manager on Windows

Last updated: 2020-10-04