Migrating IBM MQ library loading to a later version on Windows

On Windows, no change in the way IBM® MQ libraries are loaded is normally required if you upgrade from an earlier version of the product to the later version by replacing an earlier version of the product with the later version, based on the single stage scenario. However, if you choose to take advantage of multi-installation in the later version of the product, based on the side-by-side or multi-stage migration scenarios, you might have to configure the runtime environment differently, for the operating system to load the later version of the IBM MQ library.

Before you begin

To migrate applications from an earlier version of the product to the later version, you must know how the operating system loads an IBM MQ library for an application. Is the load path fixed by the application, and can you set the path in an environment variable? It is not essential to know the name of the IBM MQ library that the application loads. The library name does not change from an earlier version of the product to the later version, although the contents of the library do.

Read Multi-installation queue manager coexistence on UNIX, Linux, and Windows before starting this task.

Plan and install the later version of IBM MQ, and remember the installation name and whether the installation was set to primary.

About this task

To migrate an application from an earlier version of the product to the later version, you do not have to recompile or relink the application, because the IBM MQ libraries are compatible with later versions; see Application compatibility and interoperability with later versions of IBM MQ.

Windows searches numerous directories for load libraries, called DLLs; see Dynamic-Link Library Search Order. The build procedure for applications places the IBM MQ libraries to load before any other product libraries in the cl command. The IBM MQ .lib libraries must be in the PATH environment variable that you have specified at build time, and the DLL libraries at run time. The PATH variable is used by the application process to find the libraries it must load.

If you have followed this build procedure in the earlier release, then the effect of installing the later version of the product on the libraries that are loaded depends on which migration scenario that you are following:

Single-stage scenario

If you are replacing an earlier version of the product with the later version, based on the single stage scenario described in Migrating on Windows: single stage, you do not, in most cases, need to make any changes to the way IBM MQ libraries are loaded. The possible exception to this is if you changed the location of the libraries from the earlier version, or created symbolic links to the libraries.

Side-by-side and Multi-stage scenarios

If you have chosen a multi-installation approach to installing the later version of the product, based either on the side-by-side scenario described in Migrating on Windows: side-by-side, or the multi-stage migration scenario described in Migrating on Windows: multi-stage, you must investigate whether applications connecting to the later version of the product are linked to, and load libraries from, the correct installation and then modify the environment for the operating system to resolve IBM MQ dependencies for an application as appropriate. Typically, you can modify the runtime environment, rather than relink the application. You can use the following two commands to assist you in configuring the runtime environment:

setmqinst sets the primary installation; see setmqinst.
setmqenv initializes the command environment by setting environment variables; see setmqenv.

Table 1 summarizes the actions needed for each of these scenarios.

Table 1. Windows configurations
	Scenario	Latest version replaces earlier version in the same location Single-stage	Latest version replaces earlier version in a different location Side-by-side	Latest version alongside earlier version Multi-stage
Action	Scenario			Latest version alongside earlier version Multi-stage
setmqinst		setmqinst makes the later version installation primary. The global `PATH` is changed to point to the later version library and all Windows features work with the later version ^{See note}.		No. The later version installation can be primary, because an earlier version is installed.
No other configuration actions		Library loading works correctly. The global `PATH` contains the location of the later version libraries. Even if the later version installation is not primary, library loading works correctly. The later version libraries are in the same location as the earlier version libraries were.	Library loading probably works correctly. The library loading might not work, if the application process locally modified the `PATH` to reference the location of the earlier version libraries. A local setting of `PATH` might override the global `PATH` that is set by setmqinst.	The library loading continues to work with the earlier version correctly, nothing works with the later version.
setmqenv		Library loading works correctly. setmqenv sets the local `PATH` correctly.		Library loading works correctly, both for the earlier version and the later version. setmqenv sets the local `PATH` correctly for the later version. But the Windows features that depend on the global path do not work correctly with the later version ^{See note}. The correct earlier version is loaded, because the later version library loads the earlier version library for queue managers that have not been migrated from the earlier version.

Procedure

Consider which of the following questions apply to your configuration.
- Did you follow the build procedure documented in the product documentation for the earlier version of the product? You might be following a different build procedure tailored to your development environment, or adapted from a development tool such as Microsoft Visual Studio.
- How did you specify the load path for the earlier version?
- Is the application is loaded by another environment, such as Eclipse, or an application server? You must modify the parameters that govern how the parent environment loads applications, not the way the parent environment is loaded.
- Do the functions performed by an application require that the queue manager it connects to is associated with the primary installation?
- What constraints and requirements do you have on how the load path is specified in the later version? Security rules might restrict the use of LD_LIBRARY_PATH.
- Is the later version of the product installed alongside the earlier version? If IBM WebSphere® MQ 7.0.1 is installed:
  - You cannot make a later installation primary.
  - You cannot install the later version in the default installation path, that was referenced by applications in IBM WebSphere MQ 7.0.1.
Identify the installation of the later version of the product, from which the operating system is going to load IBM MQ libraries:
- If you have a multiple installations of the later versions to load from a server, IBM MQ checks that the installation the library was loaded from is the installation that is associated with any queue manager the application calls. IBM MQ loads the correct library if the wrong library is loaded. It is necessary to configure only one runtime environment for all IBM MQ applications.
- A typical choice is set the primary installation. Setting an installation to be primary places its library path in the global PATH variable.
- If you upgraded an earlier version installation to the later version, a link path to the earlier version installation now points to an installation containing the later version. Applications that have a fixed linkage path to the earlier version installation now load the libraries for the later installation. They are then switched to the installation that is associated with any queue manager they connect to.
- If you rebuild an application, it must link to an installation of the later version.
- If an application uses COM or ActiveX it can connect to any queue manager as long as there is a primary installation.
  Note: If an earlier version of the product is installed, COM or ActiveX server applications connect to queue managers associated only with the earlier installation. COM or ActiveX client applications are not affected by the limitation.
- If you are running the IBM MQ.NET monitor in transactional mode, the queue manager it connects to must be the primary installation.

What to do next

If you add further installations of the later version of the product, you must decide which installation to make primary, if you have chosen to make any primary. As long as applications load IBM MQ libraries from one of the later version installations, such as the primary installation, they can connect to queue managers associated with any other later version installation.

On Windows, you might build applications with different development tools. You must identify the property of the development tool that sets the PATH of the application that is being built, and not the properties of the tool itself. For example, if you are debugging with Microsoft Visual Studio, you can insert a call to setmqenv in the Environment property of the debugging section of the Configuration properties of a project.

A Windows application might call LoadLibrary and specify an explicit load path. You might build a side-by-side assembly and configure an explicit load path. If an application uses either of these mechanisms, and the later version IBM MQ library is not on the same path as the earlier release, you must recompile, or configure and relink your application to load the later version libraries.