Migrating a queue manager to a later version on UNIX and Linux

On UNIX and Linux, 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.

The upgrade from the earlier version to the latesr version of the product requires a full migration of queue managers. Create a migration plan. Use the planning task, Plan to migrate IBM MQ to a later version on UNIX and Linux, as a guide.
Review the IBM MQ system requirements for the later version; see System Requirements for IBM MQ.
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.
Review any other installed SupportPacs for their applicability to the later version.
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.

About this task

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

Log in as a user in group mqm.
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.
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.
  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 UNIX and Linux 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. For more information, see Backing up and restoring IBM MQ queue manager data.
Log in as root.
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 UNIX and Linux: single-stage.
Install the later version of the product. See the appropriate topic for the platform that your enterprise uses:
- Installing IBM MQ Server on AIX .
- Installing IBM MQ Server on Linux .
Move the queue manager to the new IBM MQ installation. We need to carry out this step, only if we are running IBM WebSphere MQ Version 7.0.1, Fix Pack 6 or later, and did not uninstall your current version of the product.
See Migrating on UNIX and Linux: side-by-side or Migrating on UNIX and Linux: multi-stage for further information.
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.

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.
Migrating on UNIX and Linux: 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 later version of IBM MQ.
Migrating on UNIX and Linux: 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 installation of the later version, 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 UNIX and Linux