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, you can create new queue managers to verify the later installation, and develop new applications. At the same time, you 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, you can reduce the peak workload on staff managing the migration.

Before you begin

Attention:

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

Copy the required information, rather than move the information, so that your existing version of IBM MQ continues to work.

Note: If you are running the IBM MQ.NET monitor in transactional mode, the queue manager it connects to must be the primary installation.

About this task

In the multi-stage migration scenario, you install the later version of the product alongside running queue managers that continue to be associated with the earlier version. You can create queue managers and run new applications using the later version installation. When you are ready to start migrating queue managers and applications from the earlier, you can do so, one-by-one. When migration to the later version is complete, you can uninstall the earlier version, and make the later version installation the primary installation.

With the multi-stage approach, until you uninstall the earlier version , you must configure an environment to run applications that connect to a queue manager to the later version. You must also provide a path to run IBM MQ commands. Both these tasks are accomplished with the setmqenv command.

Note: When you have uninstalled the earlier version, and set the later version as a primary installation, in most circumstances it is not necessary to run the setmqenv command to run applications. It is still necessary to run setmqenv to set the environment for commands that connect to a queue manager associated with an installation that is not primary.

Procedure

Install the later version in a different installation directory from the earlier version and verify the installation.
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. Verify the installation.
  
  Run the installation verification procedures and your own tests.
- You might create new queue managers running the later version, and start to develop new applications before migrating applications from the earlier version.
Configure the operating system so that applications load the libraries for the later version of the product.
1. Migrate queue managers one at a time.
  
  The first set of applications to load the libraries for the later version of the product are the applications that connect to the first queue manager you are going to migrate.
  
  It does not matter if those applications also connect to other queue managers on the server. If the applications load the later version libraries, IBM MQ automatically loads the libraries for the earlier version for those applications that connect to that version.
  
  You can either migrate the operating system environment of all applications, or just the applications that connect to the first queue manager you are going to migrate.
2. Migrate IBM MQ MQI client applications
  
  Some of the applications might be running as IBM MQ MQI client applications on another workstation. When you migrate a queue manager, clients connected to it continue to run without loading a client library for the later version.
  
  You can migrate these clients later, when you need to do so.
  Important: If any IBM MQ MQI client applications are using the library for the earlier version on the server, you must eventually migrate the clients to use the later version of the product before you uninstall the earlier version.
Migrate an application to load the new library for the later version:
- Run setmqenv to modify the local path that is searched for IBM MQ libraries.
- Relink applications with an additional runtime load path.
Consult operating system documentation about how to modify the global search path, or include a fixed runtime load path in the application load module.
To run setmqenv using the -s option:
```
"Inst_1_INSTALLATION_PATH\bin\setmqenv" -s
 
```
The -s option sets up the environment for the installation that runs the setmqenv command.
Restart the queue manager and the applications that connect to it.
1. Set up the local environment to the installation Inst_1.
```
"Inst_1_INSTALLATION_PATH\bin\setmqenv" -s
```
  The -s option sets up the environment for the installation that runs the setmqenv command.
2. Run the setmqm command to associate QM1 with Inst_1.
```
setmqm -m QM1 -n Inst_1
setmqm -m QM2 -n Inst_1
```
3. Run the strmqm command to start QM1 and migrate it to the later version.
```
strmqm QM1
strmqm QM2
```
4. Restart application 1
  - The application loads the later version library and connects to QM1, which is associated with the later version of the product.
Migrate all queue managers and applications to the later version.
- Repeat steps 2 and 4, when required, until all the queue managers and applications are migrated to the later version of the product.
Uninstall the earlier version of the product.
- When uninstalling the earlier product, you must stop all queue managers and applications that have loaded an IBM MQ library on the server. For this reason, you might choose to postpone uninstalling the earlier version of the product until a convenient maintenance window. When an earlier version of the product is not installed on a server, it is sufficient to stop the queue managers and applications that have loaded libraries from the installation that you are uninstalling or updating. It is not necessary to stop applications and queue managers associated with other installations.
1. Log in as a user in group mqm.
2. 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.
3. Stop the mqweb server that is associated with the IBM MQ installation by entering the following command:
```
endmqweb
```
4. List the state of all the queue managers on the system by using the dspmq command:
```
dspmq -a
```
5. List the status of listeners associated with a queue manager by using the DISPLAY LSSTATUS MQSC command:
```
echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName
```
6. Stop any listeners associated with the queue managers, using the endmqlsr command:
```
endmqlsr -m QMgrName
```
7. Stop each running queue manager that is associated with this installation by using the endmqm command:
```
endmqm QMgrName
```
8. Uninstall the earlier version of the product. For more information, see Uninstalling or modifying IBM MQ on Linux
Make Inst_1 the primary installation.
1. Run the setmqinst command
```
"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.
  
  You do not have to set up a search path to run IBM MQ commands from the primary installation.

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.

Now that you have uninstalled the earlier version of the product, and made the later installation primary, you can review how the application runtime environment is set. It is no longer necessary to run setmqenv to set up the search path to load libraries for the later version. If you have only one installation of the later version of the product installed, it is not necessary to run setmqenv to run commands.