Professional Documents
Culture Documents
Renate Franken
Channel Technical Sales – Germany
RenateFranken@de.ibm.com
MQ stands for Messaging and Queuing where messaging is used to exchange data as messages
rather than calling each other directly. Queuing stands for placing messages on queues in storage,
allowing programs to run independently of each other, at different speeds and times, in different
locations and without having logical connections.
WebSphere MQ, the result based on these concepts, is a reliable, scalable performing messaging and
queuing system for sending and exchanging data across applications and solutions. This also ensures
asynchronous message delivery in case the partner system is not always available.
Lab Introduction
This lab is designed for anyone who wants to get familiar with the basic functions of WebSphere
MQ. Each step introduces you to a different component or function of WebSphere MQ, showing you
how to create, administrate and use objects as base for more complex environments.
It will help you getting comfortable with the base capabilities available to you in WebSphere MQ.
After completing this lab, you will be able to accomplish the following tasks:
• Use the MQ API Sample Program to put and get data into a queue
Note:
In the following description, we use WMQ for IBM® WebSphere® MQ.
This lab was written with WMQ 6.0.2.3. But the exercise in this lab should also work with former or
later WMQ Version. It could only the one or other screen appearance looks different.
To run this WebSphere MQ Exercise without a Product Licenses or CD, use the 90 days Trial
Version from here:
http://www14.software.ibm.com/webapp/download/searchquery.jsp
(b) Start setup.exe to launch the installation. The following installation window should appear.
(c) Click on Software Requirements on the left side to check the Software prerequisites.
Note:
No means you have full Administrator rights on your machine and the WMQ Groups are
created on your local machine. Yes means you are in a Window Domain and you have
Administrator rights to create necessary WMQ groups like mqm. This is important for a
production environment. But to keep it simple for this exercise, select No.
(h) Select Accept the terms in the license agreement and click Next >
To change the installation path or to add additional components like File Transfer or Java
Extended Transaction Support, select Custom Installation.
If desired, change the installation path to e.g. C:\WMQ6 and accept the other recommended
path by clicking Next > .
(j) On the Features window, you can add additional features like Server File Transfer if
desired. But they are not required or used in the following lab. Selecting all requires about
2053MB Disk Space.
(l) Now the installation is started. It takes several minutes. Click Finish on the following screen.
Note:
After the copy and registration of WebSphere MQ, you can choose to start a default
configuration. A default configuration creates a first Queue Manager with a long name
containing the host name. It's not necessary to select Setup the Default Configuration,
because we will create and use our own Queue Manager in the next lab.
Note:
Working with Software Products, it's always advisable to check the Produkt Support Page for
recommended service or fix packs:
http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg27006037#1
At the lab creation time, Fix Pack 6.0.2.2. is the recent version. To use it, download and start
it. At this time, the executable is called WebSphereMQMDV6.0.2.2EnUs.exe. Click Next
and finally start installation through the following screens. This installation take a while.
During these labs it is assumed, that WMQ is already installed and configured, otherwise continue
with lab 1. However, we will do some checks, which are also part of the administration tasks related
to WMQ. The default installation path is C:\Program Files\IBM\WebSphere MQ\. In the following
labs, it is assumed that you have changed this default installation path C:\WMQ6\.
(a) Check if the WMQ Service is up and running. Click Start -> Control Panel - ->
Administrative Tools -> Services to start the program. It shows the status and additional
information about all registered Windows Services. Look for the service “IBM MQSeries” and
confirm that it is “Started”. If that is not so, start the service manually.
(b) Now start the WebSphere MQ Explorer via Start -> All Programs -> IBM WebSphere MQ ->
WebSphere MQ Explorer. The Explorer GUI has a common look: hierarchy and objects on the
left side; details of the actual object on the main window on the right. But currently, we have no
objects created.
Note:
To exchange messages or data via WMQ, we need queues to put and get them. To create
queues, we need a queue manager. So the first step is to create a queue manager and then the
queues. Only the WebSphere MQ Server Version can have Queue Managers and Queues. A
WebSphere MQ Client Version cannot manage theses objects. It can only access once existing
on a WebSphere MQ Server.
To create a Queue Manager, right click Queue Managers on the left window in the WMQ
explorer. Click New -> Queue Manager...
(g) On the next screen, you see the settings for listener. The port number must be unique for each
queue manager. The default is 1414.
Enter 1415 as port number. The next queue manager QMB in this lab will be 1416.
Click Finish to create the queue manager.
After creating the queue manager, it should be visible on the left side in the MQ Explorer.
Note:
A Local Queue is a local physical queue. An Alias Queue is comparable to a pointer to an
existing Local Queue. Very useful if you have to change a physical queue name and you want to
leave your application unchanged. A Model Queue is like a queue template. If you have to
create several queues with almost the same setting, you can create a Model Queue and the next
Local Queues AS this Model Queue. A Remote Queue Definition is like an Alias Queue to a
remote queue. Application can access and send messages to this queue as to a local queue. The
properties of this queue contains the queue manager and the queue name of a local queue on a
remote system.
- Finish lab 2 -
Note:
WMQ has several API's to exchange messages between applications. A message can be any kind of
data. It could be a XML messages, SOAP message, jpeg, video stream or any other kind of bit
streams. The other application can be on an other system and operation system, connected with
WMQ through several communication protocols like TCP/IP. How to connect two queue managers
will be shown in the next lab.
This lab shows how to write and read messages into a queue. To write a message into a queue, you
use the WMQ API MQPUT. To read a message from a Queue, you use the WMQ API MQGET. So
we use the WMQ terminologie put and get in the following description.
How to write or put a message into a queue and read or get messages from a queue will be shown in
this lab. WMQ provides 13 API's to access WMQ in several languages like Java, C, C++, ... .
To test WMQ and avoid to write and compile your own application, WMQ provides a graphical user
interface to run these API's. This program is named WebSphere MQ API Exerciser and can be
found in the <installationroot>\bin directory as amqapi.exe
(a) Start the WebSphere MQ API Exerciser.
To put a message into a Queue, you first have to connect to a Queue Manager, open a Queue
where you want to put the message and finally put the message. Therefore you have to
launch MQCONN, MQOPEN and then the MQPUT command.
(b) To connect to the Queue Manager QMA click MQCONN.
(d) Switch to the Queues tab, choose QLA as Selected Queue and click MQOPEN.
Check the open Status.
(e) Click MQPUT to put a message on the selected queue QLA. In the following pop-up
window, enter any text like 'My Test' and click OK.
(g) To see the content of this message, right click the queue on the right side an click Browse
Messages...
Note:
Browsing is used for displaying a message without deleting it from the queue. This is a
MQGET with a browse option set.
17. Apr. 2008 Page 19 of 41
(h) Double click the shown message, select data on the left side to see the message data.
Click Cancel. On the previous window click Close.
(i) Switch back to the WebSphere MQ API Exerciser and click MQGET. A pop up window
with the message data should appear.
Click OK to close the window.
(j) Switch back to the IBM WebSphere MQ Explorer and check the Current queue depth.
The MQGET in the API Exerciser executed a MQGET where the message on the queue was
deleted. So the Current queue depth should be 0. Sometime it's a question of the explorer's
fresh up option. If you still see a 1, click the recycle button for to refresh the MQ Explorer.
(k) Click MQCLOSE on the Queues tab to close the Queue QLA.
- End of lab 2. You should have learnt how to put and get messages -
Note:
For applications it is totally transparent whether QMB is on the same system or on another remote
system with a different operating system. The difference is the hostname which we have to specify
later on in our channel definition. In our lab, we create the second Queue Manager on our same
system for this exercise.
First we add the additional objects to QMA with the MQ Explorer. Then we use use the MQ
command line interface to setup QMB and its further objects. Sure we can also use the WMQ
Explorer to setup QMB, but we have some operation systems, e.g. AIX, which has the WMQ
Explorer. But then we still have the command line interface, we can use there.
We have already created Queue Manager QMA and the Local Queue QLA.
In addition we have to create within the QMA:
– a Local Queue with the option 'Transmission' as Transmission Queue XMITB
– a Remote Definition Queue QRB which points to the Local Queue QLB
– a Sender Channel 'QMA.QMB'.
Then we have to create the following with the WMQ command line interface:
– Queue Manager QMB
– Local Queue QLB
– Receiver Channel QMA.QMB
– Transmission Queue XMITA
– Sender Channel QMB.QMA
Test the setup with the WMQ Exerciser and put a message on QRB on QMA and check the message
on the local queue QLB on Queue Manager QMB.
(a) Create a Local Queue with the option 'Transmission' as Transmission Queue XMITB.
In the IBM WebSphere MQ Explorer right click Queues and select New -> Local Queue...
(g) Enter the Connection name and the Transmission Queue name.
The syntax of the connection name is hostname(portnumber). In our case, we enter
localhost(1416) as Connection name. If you create a Queue Manager on a different system,
you have to specify the hostname of this remote system. The portnumber is the port specified
with the listener on QMB which we do later in this lab. Enter XMITB as Transmission
queue which we have just done. Click Finish.
Note:
There is no need to do any additional settings for the Receiver Channel. Only the name must
be exactly the same as the Sender Channel which we will create next for the Queue Manager
QMB.
(i) Create the remote queue definition QRB. Therefor right click Queues within QMA and click
New->Remote Queue Definition... .
(k) The QRB is a remote queue definition which points to a the local queue QLB on the queue
manager QMB which we define in the next step. The transmission queue XMITB is used to
transfer the data from queue manager QMA to QMB. So we have now to enter here.
Enter QLB for the Remote queue (which is the local queue on QMB), enter QMB for the
Remote queue manager and enter XMITB as Transmission queue.
Enter:
crtmqm QMB
and press the enter key
(b) Start the Queue Manager QMB
Enter:
strmqm QMB
and press the enter key
(c) Create the further objects for the Queue Manager QMB. Therefore enter
runmqsc QMB
Note:
Remember that names like the channel name is case sensitive.
(h) All objects are created so far. But we still have to create and start the listener on port 1416
which is not part of the crtmqm command.
Therefore enter the following command:
DEFINE LISTENER(LISTENER.TCP) TRPTYPE(TCP)
LIKE(SYSTEM.DEFAULT.LISTENER.TCP) PORT(1416) CONTROL(QMGR)
and the following command to start the listener:
START LISTENER(LISTENER.TCP)
enter end to end the runmqsc command.
START LISTENER(LISTENER.TCP)
Note:
The parameter REPLACE means that the command will executed even if the object already
exists. The '+' sign at the end of the line can be used to split one long command into several lines.
Participants will use the WebSphere MQ API Exerciser tool to put messages on a Remote Queue
Note:
The commands for the WMQ objects are asynchronous. So getting a successful message
means that the command was started successful. It can take a few seconds until you see the
running channel. Click the refresh button at the top right of the window to update the view
until you see the Overall channel status: Running.
The IBM WebSphere MQ Explorer can be used to put a message on a queue as well.
Start the WMQ Explorer if not already started: Start -> All Programs -> IBM WebSphere MQ ->
WebSphere MQ Explorer.
(a) Right Click the QRB Queue and select Put Test Message...
Note:
If the message has not arrived, check the Current queue depth of the Transmission Queue.
Typical mistakes are: the properties (Queue name and Queue Manger name) of the Remote
Queue Definition are not correct. Another fault is that the channel is not running.
A typical mistake is the syntax of the Connection name of the sender channel.
We have already used the WMQ API Exerciser in Lab 3. WMQ has only these 13 APIs but each
API has many options. To enable the Advanced Mode in the WMQ API Exerciser, we see all these
options and can test some of them. They are identical to the options of the programming interface.
(a) Start the WebSphere MQ API Exerciser tool if not already started. Run amqapi.exe.
Enable the Advanced mode by click the check box.
Note the additional tab Attributes which appears after the Advance mode enablement.
(d) Click MQPUT to put a message into the Remote Definition Queue QRB. Take a look at the
additional tabs on the new MQPUT – Argument Options window. Before you click OK,
check out the options. Notice that the Message Descriptor tab has 7 pages to which you can
get by click the Next > button.
Note:
A WMQ Message contains a WMQ Header (MQMD – MQ Message Descriptor) and the
data itself. In the MQMD you can set options like Message ID, Message Format (e.g. String
17. Apr. 2008 Page 36 of 41
– MWFMT_STRING), Message Type (Request, Reply, Data, ... ), persistence, expiration
date, ... . Some settings are used by WMQ itself, e.g.:An expired message is deleted by
WMQ from the queue after expiration. Other options have to be handled by the receiving
application, e.g.: If the message is a request, a reply is expected, where the Reply-To-Queue
and the Reply-To-Queue Manager should be specified by the sending application in the
MQMD.
You can see the value of CURDEPTH(2) which means my current queue depth is 2.
(g) Switch to the Queue Manager tab and disconnect from the queue manager QMA. Therefor
click MQDISC.
(h) Select the Local Queue Manager QMB and click MQCONN to connect tot queue manager
QMB.
(j) As you remember, you changed the open options for the QRB open command. With these
options, you can not get the messages from the local queue QLB. So you have to change the
open options back to the previous defaults. Select MQOO_INPUT_As_Q_DEF and
deselect MQOO_OUTPUT.
(l) The following screen with the message data should appear. Click OK.
(m)Once you are sure that your scenario worked correctly, you can “MQGET” all messages
from the Queues to clear them of any content.
(n) Now create some additional Queues with names and properties of your choice. Play around
with them and make yourself familiar with the different options! Try, for example, to
“inhibit” a put and get for a queue. This way it is “protected” and its contents can not be
modified. Also do administrative tasks, like renaming objects and finally delete these «play»
Queues again!
(o) Lastly you can delete the Queue Managers “QMA” and “QMB” with all their objects!
As you already may have realized, more Queue Manager, Queues and Channels can lead to a name
confusion or conflicts. Therefore it is recommended to think about naming conventions at the
beginning of a project.
On the following page you can find more information about naming conventions:
http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg24000656&loc=en_US&cs=utf-8&lang=en
For more samples and product enhancements check the WMQ SupportPac page first:
http://www-1.ibm.com/support/docview.wss?rs=977&uid=swg27007205
For more programming samples check the <WMB installation root>\Tools\ directory.
It contains code samples and executables in several programming languages.
For more information about WMQ errors, check the file AMQERR01.log in the
<WMB installation root>\Qmgrs\<queue manager name>\errors directory.
More information about these message could be found in the WebSphere MQ Messages book:
http://www-306.ibm.com/software/integration/wmq/library/library6x.html
Here you can also find links to the support page with recommended fixes, to the library with the
product Publications and Redbooks.