What you will learn

  1. IBM MQ MacOS Toolkit set up
  2. What you can do with the Toolkit
  3. How to develop MQ apps on your Mac

IBM MQ MacOS Toolkit – what is it?

The IBM MQ MacOS Toolkit is similar to IBM MQ Clients for different platforms and to IBM MQ redistributable clients. Unlike the clients, the toolkit is provided for development purposes only. Applications built with it are not supported in production and unlike the resdistributable clients, the Toolkit cannot be distributed with applications.

The MacOS Toolkit 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 Toolkit includes native client runtime libraries, so you can run IBM MQ applications that can use the most complete MQ API – Message Queue Interface (MQI). It also includes the elements required to build C based language applications: the header files and copybooks.

    From your Mac you can now:
  • Get up and running with MQ faster, follow education materials and tutorials.
  • 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 it is running in a Docker container, Cloud platform, VM, or a supported on-premise solution.
  • Develop MQ applications natively on your Mac, using the provided C libraries to compile and unit test your code.
  • Use mqrc to get extra information on any error you see with MQ.
  • Utilise the new Node.js bindings, Go bindings and JMS-like API for Golang, which all build on the full C MQI library.

Where can you get it?

Accept the license for developers to download the IBM MQ MacOS toolkit.

How do you set it up?

After downloading the toolkit to your Mac, uncompress and untar the contents to your chosen directory.

    Add the location of the bin directories to the PATH, by editing /etc/paths.
  • your untarred folder location/IBM-MQ-Toolkit-Mac-x64-9.1.2.0/bin
  • your untarred folder location/IBM-MQ-Toolkit-Mac-x64-9.1.2.0/samp/bin

You can test that the toolkit works by issuing an MQ command in a terminal window, for example dspmqver which will output information about your Toolkit installation:

Name:        IBM MQ
Version:     9.1.2.0
Level:       p912-L190121
BuildType:   IKAP - (Production)
Platform:    IBM MQ for macOS
Mode:        64-bit
O/S:         Darwin 18.5.0
InstName:    MQNI09010200
InstDesc:    IBM MQ V9.1.2.0 (not O/S registered)
Primary:     No
InstPath:    /opt/mqm
DataPath:    /Users/janedoe/IBM/MQ/data
MaxCmdLevel: 912

The MacOS Toolkit needs a data folder for errors etc. It creates one for you when you uncompress the downloaded Toolkit package. 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. Note you must create the directory first, as the directory is not created automatically when you issue the command.

Note the InstPath : /opt/mqm output from the dspmqver command is the default installation path for Linux. There is no default installation path for the MacOS Toolkit, we’ve just created a symlink from the MacOS Toolkit ‘untarred folder location’ to this ‘familiar’ location for ease of use when testing.

Try some samples

Now that your MacOS Toolkit works, go ahead and try a sample. But first, you’ll need a queue manager and a queue. You can quickly stand up a queue manager in a Docker container or provision one in IBM Cloud.

Then take a look at this GitHub repository and try the Python, Node.js or Golang samples (we figured you already know you can develop on a Mac if you’re using JMS – we’ve provided libraries for that on Maven for a while now). There are instructions in the GitHub mq-dev patterns readme docs for each language that include the MacOS.

Where’s my message – MQ Console in browser

So you have a queue manager and you’ve managed to put some messages on a queue, but you’d like to see they made it there.

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, log in with default credentials, and you should see widgets configured to show your queue manager and any queues. In the queues widget, click the queue you put your message to, then click the four squares ‘browse messages’ icon. You should see your message.

If you’re using MQ on Cloud to provision your queue manager, see Administering a queue manager using IBM MQ Web Console. In step 9. you’ll get to start the MQ Console. Follow instructions on the same page to browse messages on your MQ on Cloud queue.

Where’s my message – MQ Explorer in Eclipse

You could 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.

True, using the MQ Explorer is not officially supported on a Mac, but it worked for us on MacOS Mojave 10.14.4, Eclipse 4.7.3a and MQ Explorer 9.1.

  1. Download Eclipse 4.7.3a for MacOS from the Eclipse SDK section on this page or directly from eclipse-SDK-4.7.3a-macosx-cocoa-x86_64.dmg.
  2. Run the installer on your Mac and drag the Eclipse icon to your Applications folder when it comes up.
  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.
  9. You might need to restart your Eclipse.
    If you’re using a different version of Eclipse, the Explorer interface might not immediately open.
  1. Click Windows -> Perspective -> Open Perspective -> MQ Explorer
  2. The Explorer interface should appear

Add your queue manager in Explorer

  1. Right click on ‘Queue managers’ in the MQ Explorer Navigator box, then ‘Add remote queue manager’. A pop up appears.
  2. Add your queue manager name – if Docker – QM1, then click Next.
  3. Add Host name or IP Address – if Docker – localhost.
  4. Add Server connection channel – if Docker – DEV.ADMIN.SVRCONN, then click ‘Next’ twice
  5. Tick ‘Enable user identification’, if Docker – default is admin. Leave ‘Prompt for password’ selected.
  6. Click Finish, then add password for user – if Docker – passw0rd. Your queue manager should appear.
  7. To check that the message you sent from your application has made it, see Verifying that the test message was sent.

If you get issues with 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.

You understand what you can do with the MacOS Toolkit, how to use it, can easily find the samples to try to connect to the queue manager so you can 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.