Windows: Migrating IBM MQ library loading from Version 7.0.1, or later, to the latest version

Investigate whether applications connecting to the latest version of the product are linked to, and load libraries from, the correct installation.

Before you begin

Read Multi-installation queue manager coexistence on UNIX, Linux, and Windows and Migrating IBM MQ library loading from an earlier version of the product to the latest version before starting this task.

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

About this task

Windows searches numerous directories for load libraries, called DLL s; see Dynamic-Link Library Search Order.

The build procedure documented for IBM WebSphere MQ 7.0.1 applications is to place 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 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, then the effect of installing the latest version of the product on the libraries that are loaded depends on the migration scenario; see Table 1.

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 latest version installation primary. The global `PATH` is changed to point to the latest version library and all Windows features work with the latest version ^{See note}.		No. The latest 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 latest version libraries. Even if the latest version installation is not primary, library loading works correctly. The latest 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 latest version.
setmqenv		Library loading works correctly. setmqenv sets the local `PATH` correctly.		Library loading works correctly, both for the earlier version and the latest version. setmqenv sets the local `PATH` correctly for the latest version. But the Windows features that depend on the global path do not work correctly with the latest version ^{See note}. The correct earlier version is loaded, because the latest version library loads the earlier version library for queue managers that have not been migrated from the earlier version.

Procedure

Identify the installation of the latest version of the product, from which the operating system is going to load IBM MQ libraries:

If you have a multiple installations of the latest 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 latest version, a link path to the earlier version installation now points to an installation containing the latest version. Applications that have a fixed linkage path to the earlier version installation now load the libraries for the latest 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 latest version.
If an application uses COM or ActiveX it can connect to any queue manager as long as there is a primary installation and it is Version 7.1 or later.
Note: If an earlier version of the product is installed, COM or ActiveX server applications connect to queue managers associated only with the Version 7.0.1 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 latest 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 latest version installations, such as the primary installation, they can connect to queue managers associated with any other latest 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 latest 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 latest version libraries.