Tuesday, February 21, 2012

Random notes about getting IBM WebSphere MQ 7.1 installed and working

I had an enormous amount of trouble while starting to develop an application that had to interface to another application using IBM WebShere MQ 7.1 message queues. Installation is not simply using the setup program's defaults. These notes are vague because this procedure was painfully time-consuming and I didn't have time to hunt down the facts about what actually got it working.

1. Installation Part I. This gets the files onto the workstation. This took me a couple days because IBM's documentation is pretty obscure about what installation set is needed, server or client, or where it puts files. A lot changed between versions 7.0 and 7.1 that was undocumented. In addition to being vague, the documentation is also inaccurate, as the documented defaults are not the real defaults. In short, to develop and test on a single machine, the Server set (which includes the Client files) was required, not just the Client set. And you had to manually select the Client files from a custom installation because - contrary to the instructions - the Client files were not selected by default.

2. Installation Part II. Once the files are physically installed, a second part of the installation runs to "prepare" the message queues. Under Windows 7 at least, this portion terminates with a "there's something wrong" error. Real helpful. Fixing this had to deal with security. In addition to the domain user required to execute services, another two separate domain users had to be created. One user is apparently to create queue managers and another to manage queues. They are identical accounts except they have different names; complete waste of resources. And you may have to start the installed services manually. As an Administrator. A Domain Administrator. WTF!

3. More security problems. Attempting to create a remote queue runs afoul of more security issues. A minimum of four layers of Authorizations have to be set up (by a local Administrator this time?) before a queue can be created. Some permissions are for creating the queue manager and some are for creating the queue.

4. Sample programs. The sample programs provided as part of the installation cannot be built using the supplied bldcssamp2.bat batch file. Firstly, because the batch file must be run from the command line, the PATH environment variable must be updated to include the compiler directory; in my case, for compiling against the .NET Framework 4.0, it was setting:

Secondly, the path to the libraries must be edited. One every compile statement. Original:

On Windows 7 (and Windows Vista, from reading other comments) the compiled executables won't run. When you launch an executable, the program crashes and the following error shows up in the Windows Application Event Log:

Activation context generation failed for "C:\Program Files (x86)\IBM\WebSphere MQ\tools\dotnet\samples\cs\base\nmqsput.exe".Error in manifest or policy file "C:\Program Files (x86)\IBM\WebSphere MQ\tools\dotnet\samples\cs\base\nmqsput.exe.Config" on line 8. The element assemblyBinding appears as a child of element configuration which is not supported by this version of Windows.

This has something to do with Windows 7 not liking the "side-by-side" Win32 manifest files that the compiler generates by default. To get around this error, the batch file had to be edited yet again. Add to every compile statement:


So, parameterizing it a bit, in the interest of helping other IBM customers, here's the complete sample build script:

SET LIBPATH=..\..\..\..\Lib
SET MFTOPT=/nowin32manifest
echo building nmqsget.exe
csc /t:exe /r:System.dll /r:amqmdnet.dll /lib:%LIBPATH% /out:nmqsget.exe %MFTOPT% nmqsget.cs

echo building nmqsput.exe
csc /t:exe /r:System.dll /r:amqmdnet.dll /lib:%LIBPATH% /out:nmqsput.exe %MFTOPT% nmqsput.cs

echo building nmqswrld.exe
csc /t:exe /r:System.dll /r:amqmdnet.dll /lib:%LIBPATH% /out:nmqswrld.exe %MFTOPT% nmqswrld.cs

echo building MQPubSubSample.exe
csc /t:exe /r:System.dll /r:amqmdnet.dll /lib:%LIBPATH% /out:MQPubSubSample.exe %MFTOPT% MQPubSubSample.cs

echo building MQMessagePropertiesSample.exe
csc /t:exe /r:System.dll /r:amqmdnet.dll /lib:%LIBPATH% /out:MQMessagePropertiesSample.exe %MFTOPT% MQMessagePropertiesSample.cs

And another thing... The documentation makes no mention about how to compile against the .NET libraries. Oh, there's a sample solution for Visual Studio, but it makes web service calls instead of using the MQ library. Wonderful, another irrelevant example. Without scanning my hard drive and digging through the command-line samples, it would have been nearly impossible to find where they buried the correct DLL that had to be referenced: C:\Program Files (x86)\IBM\WebSphere MQ\tools\Lib\amqmdnet.dll.

Fortunately, there is this outdated but still useful RedBook reference document: WebSphere MQ Solutions in a Microsoft .NET Environment. It has some helpful information about developing MQ applications in .NET and Visual Studio .NET. The conceptual information in it is still relevant for current development.