Get an IBM MQ queue for development on Windows

To see how IBM MQ works, you will be guided through creating and configuring a queue manager. Then, you will connect an application to it.

After completing the tutorial, you will be able to send messages to and retrieve messages from a queue.

You can download, install, and run IBM MQ queue manager (server) in a variety of ways:

Learning objectives

After completing this tutorial, you will understand a bit about these concepts:

  • IBM MQ queue managers
  • IBM MQ queues
  • Point-to-point messaging

Prerequisites

The tutorial steps will have you download and install each of these prerequisites:

  • A Windows 10 machine with admin privileges
  • IBM MQ Advanced for Developers
  • IBM MQ configuration (MQSC) script

Estimated time

This tutorial should take about 30-45 minutes.

Steps

  1. Download IBM MQ
  2. Install IBM MQ
  3. Create and start a queue manager
  4. Configure your queue manager
  5. Create a user and group for running MQ client applications
  6. Put and get messages to and from a queue

Step 1. Download IBM MQ

Grab IBM MQ Advanced for Developers for Windows. This is a large file, so will take some time.

Unzip the download and take note of the location of your MQ Server folder.

Step 2. Install IBM MQ

Important: If the admin user ID that you are logged in to Windows with is longer than 12 characters, you will not be able to complete this tutorial. Log out and log back in as an admin user whose user name that has less than 12 characters.

Open your command line interface ‘as administrator’. You’ll need elevated privileges to run some of the commands in this tutorial.

Construct the command that will install MQ on your machine. You need three things for this:

  • The path to the location for the MQ installer package file IBM MQ.msi, for example: C:\mqadv_dev914_windows\MQServer\MSI\IBM MQ.msi.

  • The path to a folder where MQ can create a plain text log file for the installation including the name of the file, for example: C:\Users\username\install.log.

  • The path to the location for the MQ default installation parameters file, called Response.ini, for example: C:\Users\username\Downloads\mqadv_dev914_windows\MQServer\Response.ini.

Edit this command by replacing the example paths with your three file location paths and then run it in your command line:

start /wait msiexec /i "C:\Users\username\Downloads\mqadv_dev914_windows\MQServer\MSI\IBM MQ.msi" /l*v "C:\Users\username\install.log" /q RESPONSE="C:\Users\username\Downloads\mqadv_dev913_windows\MQServer\Response.ini" TRANSFORMS="1033.mst" AGREETOLICENSE="yes" ADDLOCAL="Server"

The installation will happen in the background. To track the installation’s progress, check the log file you specified.

To check if the installation was successful, print the error level:

echo %ERRORLEVEL%

If everything went well, this will return a code 0.

Output of errorlevel command

If you get a different code and it looks like the installation failed, first check if you ran your command line tool ‘as administrator’. If not, open another command line window in ‘run as administrator’ mode and try the command again.

When the install completes successfully, there will be a new icon on your taskbar, as MQ starts automatically after being installed.

IBM MQ icon in the Windows task bar

If the installation was not successful, then check the log file to find out what happened:

notepad C:\Users\username\install.log

If the silent installation failed, you can install MQ by double clicking Setup.exe in the MQServer folder to start the Launchpad that will take you through the installation steps.

Step 3. Create and start a queue manager

The main MQ object that applications are interested in, in point to point messaging, is a queue. Before you can create a queue, you must create a queue manager. The IBM MQ queue manager is the server that hosts the queue.

If you’ve just installed MQ for the first time, the MQ installation path will be: C:\Program Files\IBM\MQ.

On your command line, change directories to the bin folder of your MQ installation, for example:

cd "C:\Program Files\IBM\MQ\bin"

Now enter:

setmqenv -s

You can now issue IBM MQ commands without having to be in the bin folder of your MQ installation.

You can display the MQ Installation and Data paths by running the “display MQ versions” command dspmqver on the command line:

dspmqver

You should see output like this:

Output from the display MQ versions command

You need a queue in order to start putting and getting your messages. Queues live on queue managers, so you need to create a queue manager first. On your command line, type:

crtmqm QM1

You should see output like this:

Output from creating a queue

The queue manager is created but not started. Start your queue manager:

strmqm QM1

You should see output like this:

Output from starting a queue

Step 4. Configure your queue manager

We’ve provided a script to help you create the MQ objects for your queue manager. We’ll get this script from GitHub by using a curl command. Make sure you run this command from a folder where you have write permissions, such as your home directory.

curl -o mq-dev-config.mqsc https://raw.githubusercontent.com/ibm-messaging/mq-dev-samples/master/gettingStarted/mqsc/mq-dev-config.mqsc

Run this command to create the MQ objects and add the location where you saved the script file, for example:

runmqsc QM1<"C:\Users\user\Downloads\mq-dev-config.mqsc"

When it’s done, you should see output like this:

Output from running mqsc script file

Are you running Windows 10 Enterprise?

If the runmqsc command fails, and you are running Windows 10 Enterprise, this is likely because your domain user is not listed as a local user on your machine. To work around this problem, you can run the Local Users and Groups Manager:

lusrmgr.msc

From there you should create a user and add it to the mqm group that was created during the MQ installation. Once you’ve done that, just run the runmqsc command as that user:

runas /user:THE_USER "runmqsc QM1<\"C:\Users\user\Downloads\mq-dev-config.mqsc\""

Now, everything should work. The script creates objects such as a queue, channel, and listener. Applications need to know about these when trying to connect to your queue manager.

Step 5. Create a user and group for running MQ client applications

The role of a user is defined through the groups they belong to. We usually want MQ applications to be run from an account without admin privileges. Your user account is an MQ admin account.

Client applications need to be authorized to perform actions like opening and closing queues, putting and getting messages etc. The client connects to the queue manager through a channel. To do this, it needs to connect from a user account that belongs to a group whose members are authorized to use the channel.

In your Windows Computer Management tool, under Local Users and Groups,

  1. Create a Windows group mqclient
  2. Create a Windows user app who is the member of the mqclient group. Set the password to passw0rd. The user will change this password the next time they log on.

You can then add authority to the mqclient group so its members can connect to the queue manager and put and get messages to and from a queue.

Run this command:

setmqaut -m QM1 -t qmgr -g mqclient +connect +inq

Then, run this command:

setmqaut -m QM1 -n DEV.** -t queue -g mqclient +put +get +browse +inq

output from setmqaut command

What you’ve done so far

You installed IBM MQ on your Windows PC, created a queue manager and ran an MQSC script to create MQ objects. Now you are ready to create and run MQ applications. MQ is using your host computer resources and connectivity.

diagram of MQ windows installation

The following objects and permissions set:

  • Queue manager QM1
  • Queue DEV.QUEUE.1
  • Channel: DEV.APP.SVRCONN
  • Listener: DEV.LISTENER.TCP on port 1414

User app, who is a member of the group mqclient is permitted to use the channel DEV.APP.SVRCONN to connect to the queue manager QM1. User/app can put and get messages to and from the queue DEV.QUEUE.1.

Step 6. Put and get messages to and from a queue

We now have an installation of MQ that lets us connect to our preset queues and send messages, so let’s send some practice messages.

We will use a sample message putting program, amqsputc, included in the MQ installation. We need to set a couple of environment variables.

set MQSERVER=DEV.APP.SVRCONN/TCP/localhost(1414)
set MQSAMP_USER_ID=app

MQSERVER specifies the endpoint of the queue manager. MQSAMP_USER_ID specifies the account that has permission to run the sample programs included with the MQ installation.

Change to the directory where the samples are:

cd C:\Program Files\IBM\MQ\tools\c\Samples\Bin64

There’s no need to log in as the user app. Just run this command to put a message:

amqsputc DEV.QUEUE.1 QM1

This should prompt you for the password for user account app. Enter passw0rd, and then you will have the option to put one or more messages, separated by pressing ENTER, onto the queue DEV.QUEUE.1. When you’re done putting messages, press ENTER twice to commit them to the queue.

you should see output similar to this:

output from putting a message on the queue

Finally, we can get the messages from our queue. Run this command:

amqsgetc DEV.QUEUE.1 QM1

Enter the password for the user app and your messages should be returned. The program waits for 15 seconds, in case new messages arrive, then exits. The returned message should look something like this:

Output from message queue

Summary

In this tutorial, you configured the queue manager running on your Windows machine for incoming client connections. The amqsputc application opened a queue and put messages to it. The amqsgetc application got messages from the same queue.

When you start developing your own client applications to connect to the queue manager, you’ll follow these steps:

  1. Configure the connection to the queue manager.
  2. Open a queue.
  3. Put a message on the queue.
  4. Get the message from the queue.
  5. Close the connection to the queue manager.

This process demonstrates the point-to-point style of messaging.

The amqsputc application acts as the producer point when it puts a message. The amqsgetc application acts as the consumer point when it gets the message from the queue.

In IBM MQ, the queue manager is effectively the server part of the system, and applications that connect to it are clients.

Usually it is the administrators that look after the MQ server where all the MQ objects are defined and the routing of messages happens. Client applications are created by developers and IBM MQ provides client libraries that developers must include in their applications. These libraries, also called MQ clients, address and use the MQ objects that admins have set up on the MQ server side. In more complex scenarios, the MQ libraries do most of the heavy messaging work for you, so you just have to learn how to use them.

Configuration is needed on both the server and the client sides for the messaging to work.

When you first start developing MQ client applications, it helps to have access to your own queue manager and a queue, for testing your client application against. Installing IBM MQ on your Windows machine gives you access to a queue manager and many options for configuring MQ objects as you begin developing your client application.

Next steps

What’s next? Write your first JMS application.