IBM Developer

Tutorial

Develop MQ applications on macOS with IBM MQ Toolkit

Build, test, and run IBM MQ messaging apps on your Mac

By Richard J. Coppen, Soheel Chughtai

On this page

The IBM MQ Toolkit for macOS lets you develop MQ applications on your Mac and interact directly with the MQ server running elsewhere. As a developer, you can use the language interfaces which are built on the platform-native C library (libmqm): C, C++, COBOL, GoLang, and Node.js.

The IBM MQ Toolkit for macOS is similar to IBM MQ Clients for different platforms and to IBM MQ redistributable clients. Unlike the clients, IBM provides the toolkit for development purposes only. Applications built with it are not supported in production and unlike the redistributable clients, you cannot distribute the IBM MQ Toolkit for macOS with applications.

The IBM MQ Toolkit for macOS includes native client runtime libraries, so you can run IBM MQ applications that can use the MQ API – Message Queue Interface (MQI). It also includes the elements required to build C based language applications.

With the IBM MQ Toolkit for macOS, you can:

  • Develop MQ applications natively on your Mac, using the provided C libraries to compile and unit test your code.
  • Run many of the existing MQ samples, such as amqsput and amqsget.
  • Administer your queue manager with MQSC commands through the provided runmqsc tool, whether the queue manager is running in a Docker container, Cloud platform, VM, or a supported on-premise solution.
  • Use mqrc to get extra information on any error you see with MQ.
  • Use the new Node.js bindings, Go bindings, and JMS-like API for Golang, which all build on the full C MQI library.

Prerequisites

These instructions are x86 specific. It is possible to follow these instructions on ARM-based macOS machines, but special consideration needs to be taken when configuring their MQ apps for TLS, as explained in this blog about messaging on Apple Silicon.

Steps

Step 1. Download the IBM MQ Toolkit for macOS

If you are familiar with Homebrew there is a tap and cask available for the IBM MQ Toolkit for macOS. Instructions on installing using the cask can be found on the Cask's homepage

If you have installed the toolkit using the homebrew cask, then you can continue to step 2.

Download the IBM MQ Toolkit for macOS. When you accept the license, the system downloads the toolkit.

Step 2. Set up the IBM MQ Toolkit for macOS

After downloading the toolkit to your Mac, double-click on the downloaded .pkg file and follow the installation steps.

Add the location of the bin directories to the PATH, by editing /etc/paths.

  • /opt/mqm/bin
  • /opt/mqm/samp/bin

You can test that the toolkit works by running dspmqver in a terminal. You should see the MQ version number, plus some other data, for example the installation path.

The IBM MQ Toolkit for macOS needs a data folder for errors and other files. The default data path is $HOME/IBM/MQ/data. You can change the default directory of the data path, by using the MQ_OVERRIDE_DATA_PATH environment variable; however, you must create the directory first.

Step 3. Try some of the sample applications

Before you can try a sample application, you need to stand up a queue manager and a queue. If you don't have them set up already, complete the steps in the "Get an IBM MQ queue for development in a container" tutorial, or provision one in IBM Cloud by completing the steps in the "Get an IBM MQ queue for development in IBM Cloud" tutorial.

Then, take a look at the IBM Messaging samples and patterns GitHub repository and try the Python, Node.js, or Golang samples. If you use JMS, you already know you can develop on a Mac, so IBM has provided IBM MQ JMS libraries on Maven for a while now. There are instructions in the readme docs for each language.

If you are familiar with MQ, you will find the packaged samples in: /opt/mqm/samp/bin

Step 4. Check that the messages made it onto a queue

You have a queue manager, and you put some messages on a queue. Now you want to check whether the messages made it onto the queue. You can either use the MQ Console in a browser or you can use the MQ Explorer.

Viewing messages in MQ Console in a browser

You can use MQ Console in your browser to check whether the message has made it onto a queue.

If you’re using Docker to stand up your queue manager, MQ console should already be configured. Go to https://localhost:9443/ibmmq, and log in with the default credentials. See Step 4 in "Get an IBM MQ queue for development in a container" tutorial to learn how to browse messages on your queue using the MQ Console.

If you're using MQ on Cloud to provision your queue manager, see Administering a queue manager using IBM MQ Web Console. Follow instructions on the same page to browse messages on your MQ on Cloud queue.

Viewing messages in MQ Explorer in Eclipse

You can also use the MQ Explorer to connect to the queue manager and check your queue and messages. There is an MQ Explorer plug in for Eclipse.

  1. Visit the Eclipse marketplace and identify a suitable Eclipse version for your macOS environment.

  2. If you need to install a version of Eclipse to host the IBM MQ Explorer plugin, then visit the Eclipse download page, select R Packages, and download the Eclipse IDE.

  3. From the Eclipse marketplace MQ Explorer page, click the fourth orange download icon under the install by dragging button.

  4. From the pop-up that appears, copy the URL that you need for Eclipse.

  5. Open Eclipse.

  6. From the Help menu for Eclipse, go to Install new software.

  7. In Eclipse Install window, in the Work with field, paste the link you just copied from Eclipse Marketplace MQ Explorer page. MQ Explorer appears as a list item in the Name/Version box.

  8. Click Finish. The Explorer interface appears. (You might need to restart your Eclipse.)

If you’re using a different version of Eclipse, the Explorer interface might not immediately open.

If so, Click Windows -> Perspective -> Open Perspective -> MQ Explorer. The MQ Explorer interface should now appear.

To add your queue manager in MQ Explorer, complete these steps:

  1. Right-click Queue managers in the MQ Explorer Navigator box, and then select Add remote queue manager. A pop up appears.
  2. Add your queue manager name. If Docker, use QM1. Then, click Next.
  3. Add Host name or IP Address. If Docker, use localhost.
  4. Add Server connection channel. If Docker, use DEV.ADMIN.SVRCONN. Then, click Next twice.
  5. Check Enable user identification. If Docker, the default is admin. Leave Prompt for password selected.
  6. Click Finish.
  7. Add the password for user. If Docker, use passw0rd. Your queue manager should appear.

To check that the message you sent from your application has made it, see Verifying that the test message was sent in the documentation.

If you run into issues with MQ Explorer, and the Eclipse version you have is not 4.7.3a, you might have to uninstall the version that you have and roll back or up to eclipse-SDK-4.7.3a-macosx-cocoa-x86_64.dmg.

Summary and next steps

In this tutorial, you learned what you can do with the IBM MQ Toolkit for macOS, how to use it, and where to find the samples to connect to the queue manager and put and get messages to and from a queue. If your queue manager is running in Docker or you’ve provisioned it in IBM Cloud, you can use MQ Explorer on your Mac or MQ Console in the browser to check your messages have made it on the queue.