Tutorial
Get an IBM MQ queue for development on Windows
Configure your queue for app connections
On this page
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:
- In a container or Red Hat OpenShift Container Platform.
- In the IBM Cloud, AWS (or AWS using Ansible or AWS using Terraform), Microsoft Azure, or Google Cloud.
- On various operating systems: Linux/Ubuntu or Windows (this tutorial). For macOS, use MQ on Containers.
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
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 username 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_dev930_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_dev930_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:
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:
If everything went well, this will return a code 0.
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 installation completes successfully, there will be a new icon on your taskbar, as MQ starts automatically after being installed.
If the installation was not successful, then check the log file to find out what happened:
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:
Now enter:
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:
You should see output like this:
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:
You should see output like this:
The queue manager is created but not started. Start your queue manager:
You should see output like this:
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.
Run this command to create the MQ objects and add the location where you saved the script file, for example:
When it's done, you should see output like this:
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:
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:
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,
- Create a Windows group
mqclient
- Create a Windows user
app
who is the member of themqclient
group. Set the password topassw0rd
. The user will change this password the next time they log on.
You can then add authority to the mqclient
group so that its members can connect to the queue manager and put and get messages to and from a queue.
Run this command:
Then, run this 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.
The following objects and permissions set:
Queue manager QM1
Queue DEV.QUEUE.1
- Channel:
DEV.APP.SVRCONN
- Listener:
SYSTEM.LISTENER.TCP.1
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.
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:
There's no need to log in as the user app
. Just run this command to put a message:
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:
Finally, we can get the messages from our queue. Run this command:
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:
To learn how to install, access, and put and get a message on the queue using the MQ Console, follow the steps in this tutorial.
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:
- Configure the connection to the queue manager.
- Open a queue.
- Put a message on the queue.
- Get the message from the queue.
- 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.