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

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 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:

Allows you to add or modify CCSID entries
Specify default data conversion
Specify data for different command levels

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

Linux® - all versions
Windows

If you 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.

About this task

In the single-stage migration scenario, the installation of the later version of the product replaces an earlier version in the same installation location.

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, you 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 you 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 a server installation using the Installation Launchpad.

You 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

Log in as a user in group mqm.
Stop all applications using the IBM MQ installation.

If you 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.
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.
  
  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, 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: 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
```
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.
Stop the IBM MQ Service and exit the Service icon application.
Optional: Optionally uninstall the current version of the product.
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, you can do this either by using the Installation Launchpad or by using the msiexec command. For more information, see:
  - Upgrading an IBM MQ server installation using the Launchpad
  - Upgrading an IBM MQ server installation using msiexec
  On Windows, uninstalling the previous version of the product before you install the later version is optional.
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.
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
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
```
  If you are migrating between any 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
```
  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, you 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 ¹An IBM MQ 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

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

¹ 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 loaded at runtime.