{"id":513,"date":"2018-06-05T00:34:29","date_gmt":"2018-06-04T23:34:29","guid":{"rendered":"https:\/\/marketaylor.synology.me\/?p=513"},"modified":"2019-11-24T14:59:11","modified_gmt":"2019-11-24T14:59:11","slug":"easier-use-of-the-node-js-interface-for-mq","status":"publish","type":"post","link":"https:\/\/marketaylor.synology.me\/?p=513","title":{"rendered":"Easier use of the Node.js interface for MQ"},"content":{"rendered":"

In November, I wrote<\/a> about a new language binding to MQ, making it possible to use Javascript in a Node.JS environment to access the MQ API. I published the first release of that code only through GitHub<\/a> which required that you clone it locally before you could use it. Once the initial public exposure proved some stability to the interface, I added the ibmmq package to the npm repository<\/a> meaning that you could simply refer to it in the descriptors (package.json) for your programs and npm would automatically download and install it.<\/p>\n

But there was still one drawback. The package builds on, and requires, the MQ C client runtime libraries. That needed a separate operation to complete the installation, as those libraries came from product installation media or required you to login to an authorised location before they could be accessed.<\/p>\n

No longer though.<\/p>\n

Recent updates to the MQ Redistributable Client package and then to the MQ Node.js component have made it much simpler to get an MQ application running, and to create standalone containers for those applications.<\/p>\n

<\/p>\n

The MQ Redistributable Client<\/h2>\n

This package was designed to make it possible to embed the essential MQ runtime files alongside an application, making it possible to distribute a standalone resource.<\/p>\n

Jon Rumsey wrote more about it here<\/a>.<\/p>\n

The two primary application platforms \u2013 Linux x64 and Windows \u2013 are supported by this component.<\/p>\n

Earlier this year, the latest versions of the Redistributable Client were put into the same public repository as the full MQ Advanced Server for Developers product. That makes it possible to download the file directly without needing any login credentials. (The corresponding solution for the Java variant of the Redistributable Client was to put it on the Maven Central Repository<\/a>.)<\/p>\n

Automatic installation with the Node.js package<\/h2>\n

The MQ Node.js package now exploits that easy access to the C runtime to download it as part of its own installation.<\/p>\n

When you write a Node.js program, the description of the program in package.json<\/em> lists which other packages are required. Running npm install<\/code> for your application tries to download those prerequisite packages (and their dependencies) from the npm repository. Part of the ibmmq package includes directives (also written in JavaScript) for a postinstall step that pulls down that tar or zip file during the npm installation process. The postinstall code then unpacks the image and deletes many of the files, leaving just the pieces needed for actually running a C application.
\nFor example, using one of the sample programs included with this package, and creating a basic package file:<\/p>\n

$ cat package.json\n{\n  \"name\": \"amqsput\",\n  \"version\": \"0.0.1\",\n  \"description\": \"For demonstrating automatic installation of MQ API\",\n  \"main\": \"amqsput.js\",\n  \"dependencies\": {\n    \"ibmmq\": \">=0.7.0\"\n  }\n}\n<\/pre>\n
Then running the installation step, which shows the download of the C libraries:<\/p>\n
$ npm install\n... (various messages showing installation of other pieces) ...\n> ibmmq@0.7.0 postinstall \/tmp\/nodetest\/node_modules\/ibmmq\n> node postinstall.js\n\nDownloading  IBM MQ Redistributable C Client runtime libraries - version 9.0.5.0<\/strong>\nUnpacking libraries...<\/strong>\nRemoving 9.0.5.0-IBM-MQC-Redist-LinuxX64.tar.gz\namqsput@0.0.1 \/tmp\/nodetest\n\u2514\u2500\u252c ibmmq@0.7.0\n\u251c\u2500\u252c ffi@2.2.0\n\u2502 \u251c\u2500\u2500 bindings@1.2.1\n\u2502 \u251c\u2500\u252c debug@2.6.9\n... (more about the dependency tree)\n<\/pre>\n
Now the amqsput program is ready to run with no further intervention<\/p>\n
$ node amqsput\nSample AMQSPUT.JS start\nMQCONN to QM1 successful\nMQOPEN of SYSTEM.DEFAULT.LOCAL.QUEUE successful\nMQPUT successful\nMQCLOSE successful\nMQDISC successful\n<\/pre>\n
Disabling the automatic installation<\/h2>\n
It is possible to disable the automatic download of the MQ C runtime. You may have a preferred version of the MQ client libraries, or you may already have installed the client for other reasons and want to reuse the same installation.<\/p>\n
Set the environment variable MQIJS_NOREDIST to any value and the file is not downloaded:<\/p>\n
$ export MQIJS_NOREDIST=true\n$ npm install\n... (various messages showing installation of other pieces) ...\n> ibmmq@0.7.0 postinstall \/tmp\/nodetest\/node_modules\/ibmmq\n> node postinstall.js\n\nEnvironment variable set to not install IBM MQ Redistributable C Client<\/strong>\namqsput@0.0.1 \/tmp\/nodetest\n\u2514\u2500\u2500 ibmmq@0.7.0\n<\/pre>\n
Platform support<\/h3>\n
The redistributable clients are only available for Linux x64 and Windows. The automatic installation attempt is bypassed if you are running on a platform that does not have the Redistributable Client available. In those circumstances, you will have to get the libraries from a more traditional route. And of course, there are platforms where Node.js runs but there is no MQ client available at all. For that situation, you will have to find a completely different mechanism such as running in a VM or container.<\/p>\n
What parts are kept<\/h3>\n
The full Redistributable Client packages contain much more than the libraries needed to run a C program. Most of the rest of that package gets deleted by the unpacking process, but one program is left alone \u2013 runmqsc<\/strong>. That is done so that it is possible to use this downloaded image to create Client Channel Definition Tables (CCDT) from just within the Node directory by using runmqsc with the -n flag. And that in turn is done because you may want to use this solution within a container for simpler deployment. Which is the subject of the next section.<\/p>\n
Docker container<\/h2>\n
Included with the ibmmq package is an example for how to build a Docker container that runs an MQ Node.js program.<\/p>\n
The Dockerfile shows one way to build from a base image, and add a program along with its prereqs. A script runs the build and then executes the program. The script sets some environment variables including MQSERVER to point at a queue manager.<\/p>\n
Unsurprisingly in this case, the program did not have credentials for a successful client connection. But it demonstrates the principle is correct after getting as far as making the initial connection to the remote queue manager.<\/p>\n
$ cd node_modules\/ibmmq\/samples\n$ .\/run.docker\nSending build context to Docker daemon  87.04kB\nStep 1\/13 : FROM debian:jessie-slim\n---> f1ff1c889d54\nStep 2\/13 : ENV NODE_USER app\n...\nStep 13\/13 : CMD node amqsput ${DOCKER_Q} ${DOCKER_QMGR}\n---> Using cache\n---> 0cd6e7086633\nSuccessfully built 0cd6e7086633\nSuccessfully tagged mq-node-demo:latest\nSample AMQSPUT.JS start\nMQ call failed in CONNX: MQCC = MQCC_FAILED [2] MQRC = MQRC_NOT_AUTHORIZED [2035]\n<\/pre>\n
Client connections<\/h2>\n
For simplicity, the sample script for building the image takes the most basic approach for defining the client connection. In the docker run command it sets the MQSERVER environment variable. But I have played with a couple of other mechanisms.<\/p>\n