IBM Software Group

WebSphere MQ Basic Functions and Commands for New Users

Valerie Lampkin vlampkin@us.ibm.com WebSphere MQ Support April 28, 2010

WebSphere Support Technical Exchange

IBM Software Group

Agenda
MQ Files and Commands MQ Objects Logging Dead Letter Queue (DLQ) Security/Authorization Listener Triggering Clustering Troubleshooting

WebSphere Support Technical Exchange

2 of 43

IBM Software Group

Quick Beginnings
The Quick Beginnings Guides can be viewed at the infocenter: http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/ index.jsp mqconfig script is a useful tool to check that semaphores, shared memory, and other settings meet the minimum recommendations for WebSphere MQ http://www-01.ibm.com/support/docview.wss? rs=171&uid=swg21271236 AIX is self-tuning, other platforms may require kernel tuning parameter adjustments. Special considerations for Solaris 10 projects.

WebSphere Support Technical Exchange

3 of 43

IBM Software Group

Websphere MQ File Systems

The installation directory for MQ product code is
/opt/mqm for most platforms (/usr/mqm for AIX). Working data is stored in /var/mqm. You cannot change these locations. Recommended to create separate file systems for log data /var/mqm/log and error files /var/ mqm/errors. The /var/mqm/log file system is where active logs are stored. MQ errors logs and FDC files are written to /var/mqm/errors. The queues and QMGR logs are in /var/mqm/qmgrs.
WebSphere Support Technical Exchange 4 of 43

IBM Software Group

MQ Files Continued
The /opt/mqm (/usr/mqm for AIX) file system contains
binary MQ executibles in the bin directory. Sample MQ programs are located in the samp directory. Some of the most popular sample programs are: amqsput PUT amqsbcg BROWSE amqsget GET

WebSphere Support Technical Exchange

5 of 43

IBM Software Group

Configuration Files
mqs.ini - There is one mqs.ini file which effects
WebSphere MQ on node as a whole. Location is in /var/mqm directory contains defaults and lists all QMGRS defined on node. qm.ini There is a qm.ini file for each QMGR. It effects changes for specific qmgr. Location is in /var/mqm/qmgrs/QMGRNAME Any changes you make to a configuration file usually do not take effect until the next time the queue manager is started. Values defined in the qm.ini files take precedence over values defined in the mqs.ini file
WebSphere Support Technical Exchange 6 of 43

IBM Software Group

Control Commands
Commands are case sensitive and lower case.
These are some of the most common:
crtmqm creates QMGR strmqm starts QMGR endmqm ends QMGR (may take a while if i option not used) dltmqm deletes QMGR (be sure you have backup) runmqsc starts MQ script
To see all available control commands, refer to the System
Administration Guide http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/advanced/ content.jsp
7 of 43

WebSphere Support Technical Exchange

IBM Software Group

Default QMGR
You can create a default queue manager using
the crtmqm command with the -q flag The Default QMGR is specified in the mqs.ini file. To make an existing queue manager the default, add following stanza to mqs.ini file:
DefaultQueueManager: Name=TESTQMGR

Changing the default qmgr can affect other users

or applications. Any applications connecting after you have changed the default connect to the new default qmgr.

WebSphere Support Technical Exchange

8 of 43

IBM Software Group

RUNMQSC
Use the runmqsc command to issue MQSC
commands to a queue manager. MQSC commands enable you to perform administration tasks, for example defining, altering, or deleting a local queue object. Very useful to display, alter, define, delete,start, stop, etc. You can view all runmqsc commands in the Script (MQSC) Command Reference manual. http://publib.boulder.ibm.com/infocenter/wmqv6/ v6r0/topic/com.ibm.mq.csqzaj.doc/sc10120_.htm
WebSphere Support Technical Exchange 9 of 43

IBM Software Group

QUEUES
Queue types local queues (normal and xmitq) alias queue (points to targq) remote queue (points to queue on remote qmgr actual put is to local xmitq) cluster queue (many different types of queues which are broadcast as part of a cluster) model queue (template for dynamic queues)

WebSphere Support Technical Exchange

10 of 43

IBM Software Group

Queue Name Resolution

Link to name resolution table that will help clarify how messages are routed http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/topic/ com.ibm.mq.csqzal.doc/fg12170_.htm

WebSphere Support Technical Exchange

11 of 43

IBM Software Group

CHANNELS
Different types of channels: SDR, SVR, RCVR, RQSTR,
CLNTCONN, SVRCONN, CLUSSDR, CLUSRCVR sender/receiver channel pair defined between two QMGRS

On the next slide we will look at common example of a

WebSphere Support Technical Exchange

12 of 43

IBM Software Group

Channel Example
W hen a message is put on QMGR1 to a qremote definition where the target queue exists on QMGR2, it actually is put to the XMITQ (named QMGR2). If channel triggering is properly enabled, this will allow the SDR channel QMGR1.QMGR2 to start and the MCA (Message Channel Agent) will start the RCVR channel QMGR1.QMGR2 on QMGR2. Once the channels are running, the message will be read off XMITQ and sent across channel to the target queue on QMGR2.

QMGR1
Sender Channel: QMGR1.QMGR2 Receiver Channel: QMGR2.QMGR1 XMITQ: QMGR2
WebSphere Support Technical Exchange

QMGR2
Sender Channel: QMGR2.QMGR1 Receiver Channel: QMGR1.QMGR2 XMITQ:QMGR1
13 of 43

IBM Software Group

Logging
Circular vs. Linear lc or ll during crtmqm The total number of primary and secondary log
files cannot exceed 511 on UNIX systems, or 255 on Windows Log file size may not be altered after queue manager creation Log control file is amqhlctl.lfh Default location of logs
UNIX: /var/mqm/log/<qmname> Windows: C:\Program Files\IBM\WebSphere MQ\log\<qm name>
WebSphere Support Technical Exchange 14 of 43

IBM Software Group

Logging continued
Developerworks article with guidelines for Configuring
and tuning WebSphere MQ for performance on Windows and UNIX covers log extents, log buffer size, etc.

http://www.ibm.com/developerworks/websphere/library/ techarticles/0712_dunn/0712_dunn.html

WebSphere Support Technical Exchange

15 of 43

IBM Software Group

UNIX Log Defaults

LogPrimaryFiles=3 LogSecondaryFiles=2 LogFilePages=1024 LogType=CIRCULAR LogBufferPages=0 LogDefaultPath=/var/mqm/log

WebSphere Support Technical Exchange

16 of 43

IBM Software Group

Common log error message

AMQ7469: Transactions rolled back to release log space. Increasing log numbers may not be the correct answer
investigate why transactions are not committed in a timely manner

WebSphere Support Technical Exchange

17 of 43

IBM Software Group

Dead Letter Queue (DLQ)

When messages can not be delivered to their intended
destination they may be sent to a Dead Letter Queue MQ provides an automated way of handling these Dead Letter messages the Dead Letter Queue handler, invoked by runmqdlq command, is the default routine supplied by MQ We recommend all QMGRs have a DLQ configured. Can be added via runmqsc alter qmgr command or can be done during crtmqm with u option
(i.e. crtmqm -u SYSTEM.DEAD.LETTER.QUEUE TESTQMGR)

WebSphere Support Technical Exchange

18 of 43

IBM Software Group

Alter QMGR to configure DLQ

QMNAME(TESTQMGR) ACCTCONO(DISABLED) ACCTINT(1800) ACCTMQI(OFF) ACCTQ(OFF) ACTIVREC(MSG) ALTDATE(2010-02-08) ALTTIME(13.07.39) AUTHOREV(DISABLED) CCSID(1208) CHAD(DISABLED) CHADEV(DISABLED) CHADEXIT( ) CHLEV(DISABLED) CLW LDATA( ) CLW LEXIT( ) CLW LLEN(100) CLW LMRUC(999999999) CLW LUSEQ(LOCAL) CMDLEVEL(600) COMMANDQ(SYSTEM.ADMIN.COMMAND.QUEUE) CRDATE(2010-02-08) CRTIME(13.07.06) DEADQ(SYSTEM.DEAD.LETTER.QUEUE)

WebSphere Support Technical Exchange

19 of 43

IBM Software Group

Sample DLQ browse (using amqsbcg)

AMQSBCG0 - starts here ********************** MQOPEN - 'SYSTEM.DEAD.LETTER.QUEUE' MQGET of message number 1 ****Message descriptor**** StrucId : 'MD ' Version : 2 Report : 0 MsgType : 8 Expiry : -1 Feedback : 0 Encoding : 273 CodedCharSetId : 819 Format : 'MQDEAD Priority : 0 Persistence : 1 MsgId : X'414D5120626F776D616E676120202020524E244220001501' CorrelId : X'000000000000000000000000000000000000000000000000' BackoutCount : 0 ReplyToQ : ' ' ReplyToQMgr : vlampkin ** Identity Context UserIdentifier : vlampkin ' AccountingToken : X'16010515000000030D6D3BAB5CDD6E5F7E9E53EB03000000000000000000000B' ApplIdentityData : ' ' ** Origin Context PutApplType : '11' PutApplName : WebSphere MQ\bin\amqsputc.exe'

WebSphere Support Technical Exchange

20 of 43

IBM Software Group

Hex 805 = 2053 return code (Queue Full)

PutDate : '20050301' PutTime : '12044424' ApplOriginData : ' ' GroupId : X'000000000000000000000000000000000000000000000000' MsgSeqNumber : '1' Offset : '0' MsgFlags : '0' OriginalLength : '-1' **** Message **** length - 194 bytes 00000000: 444C 4820 0000 0001 0000 0805 5445 5354 'DLH ........TEST 00000010: 2020 2020 2020 2020 2020 2020 2020 2020 ' 00000020: 2020 2020 2020 2020 2020 2020 2020 2020 ' 00000030: 2020 2020 2020 2020 2020 2020 4741 4220 ' GAB 00000040: 2020 2020 2020 2020 2020 2020 2020 2020 ' 00000050: 2020 2020 2020 2020 2020 2020 2020 2020 ' 00000060: 2020 2020 2020 2020 2020 2020 0000 0222 ' ..." 00000070: 0000 01B5 4D51 5354 5220 2020 0000 0006 '...MQSTR .... 00000080: 616D 7172 6D70 7061 2020 2020 2020 2020 'amqrmppa 00000090: 2020 2020 2020 2020 2020 2020 3230 3035 ' 2005 000000A0: 3033 3031 3132 3439 3531 3735 7465 7374 '030112495175test 000000B0: 206F 6620 4D65 7373 6167 6520 746F 2044 ' of Message to D 000000C0: 4C51 'LQ

WebSphere Support Technical Exchange

21 of 43

IBM Software Group

Runmqdlq
Example: runmqdlq DLQ QMGR < rules.txt where DLQ = name of your dead letter q QMGR = queue manager name and rules.txt is a file with your rules table The rules table file can contain information such as WAIT, RETRY, FWD

WebSphere Support Technical Exchange

22 of 43

IBM Software Group

Security/Authorization
Authorization for using MQI calls, commands,
and access to objects is provided by the Object Authority Manager (OAM). The setmqaut command is used to grant or revoke authorizations as required. A security refresh is required after setmqaut commands are issued. This can be done by recycle of QMGR to refresh the security cache or by runmqsc command refresh security(*) all dspmqaut and dmpmqaut can be used to view authorities.
WebSphere Support Technical Exchange 23 of 43

IBM Software Group

WebSphere MQ Listener
The WebSphere MQ listener (runmqlsr) is a TCP/IP server program. Normally listens for connections on default port 1414. It can listen on a specific network address instead; port number is configurable With new versions of MQ, can be invoked via command line or defined as object

Example: runmqlsr -t tcp -m QMNAME -p 1822 DEFINE LISTENER(TEST.LISTENER) TRPTYPE(TCP )

PORT(1555) CONTROL(QMGR)
WebSphere Support Technical Exchange 24 of 43

IBM Software Group

KeepAlive
WebSphere MQ will enable KeepAlive if requested by inserting stanza in qm.ini file. TCP: KeepAlive=Yes When KeepAlive is enabled for a connection 1. The system starts a timer for the connection 2. The system resets this timer whenever packets arrive 3. The system tests the connection when the timer expires 4. The system aborts the connection if there is no response

WebSphere Support Technical Exchange

25 of 43

IBM Software Group

Triggering
A message is put to a queue defined as triggered
(may be first, depth, or every) If a series of conditions are met, the queue manager sends a trigger message to an initiation queue. This is called a trigger event. A trigger monitor reads the trigger message and takes the appropriate action based on the contents of the message, which is typically to start a program to process the triggered queue.
WebSphere Support Technical Exchange

26 of 43

IBM Software Group

TRIGTYPE
FIRST: A trigger event occurs when the current depth of the
triggered queue changes from 0 to 1. Use this type of trigger when the serving program will process all the messages on the queue (i.e. until MQRC_NO_MSG_AVAILABLE). EVERY: A trigger event occurs every time a message arrives on the triggered queue. Use this type of trigger when the serving program will only process one message at a time. DEPTH: A trigger event occurs when the number of messages on the triggered queue reaches the value of the TRIGDPTH attribute. Use this type of trigger when the serving program is designed to process a fixed number of messages (i.e. all replies for a certain request). Note: W hen triggering by depth, triggering is disabled and must be re-enabled by using MQSET or ALTER QLOCAL.

WebSphere Support Technical Exchange

27 of 43

IBM Software Group

Triggering Set Up
Create an initiation queue or use the default
SYSTEM.DEFAULT.INITIATION.QUEUE.

Create a process definition. Create or alter a local or model queue. Associate the initiation queue and process definition with
the local queue, and specify the trigger attributes .

WebSphere Support Technical Exchange

28 of 43

IBM Software Group

Trigger Troubleshooting
Verify the application name is correct and exists verify the application is coded correctly - verify the correct authorizations are in place. Verify a trigger monitor is active. May want to start runmqtrm as nohup. Verify trigger type matches application design. Try manually starting the triggered application to see if it is able to run.

WebSphere Support Technical Exchange

29 of 43

IBM Software Group

Cluster QMGRs, showing manual and auto-defined channels

WebSphere Support Technical Exchange

30 of 43

IBM Software Group

Clustering
SYSTEM.CLUSTER.TRANSMIT.QUEUE is the
xmitq through which all messages (data and admin) are sent between qmgrs within a cluster each QMGR has its own SCTQ which is created as default during crtmqm. Workload algorithm determines how messages are routed expected round robin may not always occur as customer expects. There are 12 steps which may affect how cluster routes messages. http://publib.boulder.ibm.com/infocenter/wmqv6/ v6r0/topic/com.ibm.mq.csqzah.doc/ qc10940_.htm
WebSphere Support Technical Exchange 31 of 43

IBM Software Group

Clustering Tips
AMQRRMFA is the repository manager process which governs all cluster
activity for a queue manager.

Every cluster has at least one (preferably two) queue managers holding full

repositories of information about the queue managers, queues, and channels in a cluster definitions in order to join a cluster.

Queue managers need a cluster-receiver and a cluster-sender channel Each queue manager that joins a cluster will need to have a manually

defined cluster-sender (CLUSSDR) channel to one of the full repositories. in a cluster.

You can only GET from a local cluster queue, but you can PUT to any queue

WebSphere Support Technical Exchange

32 of 43

IBM Software Group

Cluster Troubleshooting
For investigation of clustering issues, please
collect cluster "must gather" documentation any FDCs from /var/mqm/errors directory AMQERR0#.LOG files from /var/mqm/qmgrs/ <qmgrname>/errors directory dump of cluster using amqrfdm and runmqsc output as described in link below http://www-01.ibm.com/support/docview.wss? rs=171&uid=swg21293315.

WebSphere Support Technical Exchange

33 of 43

IBM Software Group

Cluster References
Queue Manager Clusters online manual:
http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/topic/ com.ibm.mq.csqzah.doc/qc10140_.htm

WebSphere Support Technical Exchange

34 of 43

IBM Software Group

Must Gather
MustGather documents aid in problem determination and save time resolving WebSphere MQ Problem Management Records (PMRs). http://www.ibm.com/support/docview.wss? acss=wmq091808&rs=171&uid=swg21229861

WebSphere Support Technical Exchange

35 of 43

IBM Software Group

Troubleshooting
FDCs are written to /var/mqm/errors directory. MQ names
the files AMQxxxxx.y.FDC where xxxxx is the process number QMGR logs are located in /var/mqm/qmgrs/QMGRNAME/errors directory. Current messages are always appended to the first error log AMQERR01.LOG

WebSphere Support Technical Exchange

36 of 43

IBM Software Group

Sample FDC
| WebSphere MQ First Failure Symptom Report | | ========================================= | Date/Time :- Monday January 25 16:16:23 EST 2010 | | Host Name :- aemtux2 (Linux 2.6.5-7.319-pseries64) | | PIDS :- 5724H7207 | | LVLS :- 6.0.2.8 | | Product Long Name :- WebSphere MQ for Linux (POWER platform) | Vendor :- IBM | | Probe Id :- CO052000 | | Application Name :- MQM | | Component :- cciTcpReceive | | SCCS Info :- lib/comms/amqccita.c, 1.255.1.38 | | UserID :- 00007100 (vlampkin) | | Program Name :- amqrmppa | | Addressing mode :- 64-bit | | Process :- 4544 | | Thread :- 6 | | ThreadingModel :- PosixThreads | | QueueManager :- VALCLUSTER | | Major Errorcode :- rrcE_BAD_DATA_RECEIVED | | Minor Errorcode :- OK | | Probe Type :- MSGAMQ9207 | | Probe Severity :- 2 | | Probe Description :- AMQ9207: The data received from host 'iss03 | (9.42.115.203)' is not valid. | | FDCSequenceNumber :- 0 | | Comment1 :- iss03 (9.42.115.203) | | Comment2 :- TCP/IP | +-----------------------------------------------------------------------------+ MQM Function Stack ccxResponder rrxResponder rriAcceptSess ccxReceive cciTcpReceive xcsFFST | |

WebSphere Support Technical Exchange

37 of 43

IBM Software Group

FFSTSummary
AMQ4556.0.FDC 2010/01/25 21:16:15 amqrmppa 4556 7 CO052000 cciTcpReceive
rrcE _BAD_DATA_RECEIVED OK AMQ3635.0.FDC 2010/01/25 21:16:17 amqrmppa rrcE _BAD_DATA_RECEIVED OK AMQ3190.0.FDC 2010/01/25 21:16:19 amqrmppa rrcE _BAD_DATA_RECEIVED OK AMQ4556.0.FDC 2010/01/25 21:16:21 amqrmppa rrcE _BAD_DATA_RECEIVED OK AMQ4544.0.FDC 2010/01/25 21:16:23 amqrmppa rrcE _BAD_DATA_RECEIVED OK 3635 6 CO052000 cciTcpReceive 3190 11 CO052000 cciTcpReceive 4556 8 CO052000 cciTcpReceive 4544 6 CO052000 cciTcpReceive

May be many FDCs often the first has the most significant information and subsequent files may be fallout from the first error encountered.

WebSphere Support Technical Exchange

38 of 43

IBM Software Group

Return Codes/Error messages

mqrc command can be used to check error codes and return codes
Example: Prompt> mqrc 2053 2053 0x00000805 MQRC_Q_FULL Prompt> mqrc AMQ9207 536908295 0x20009207 rrcE_BAD_DATA_RECEIVED MESSAGE: The data received from host '<insert one>' is not valid. EXPLANATION: Incorrect data format received from host '<insert one>' over <insert two>. It may be that an unknown host is attempting to send data. An FFST file has been generated containing the invalid data received. Can check Messages manual online for codes: http://publib.boulder.ibm.com/infocenter/wmqv6/v6r0/topic/com.ibm.mq.amqzao.doc/csq05rea3.htm

WebSphere Support Technical Exchange

39 of 43

IBM Software Group

TRACING
Normally wed request a high detail trace. Trace output files will be in /var/mqm/trace directory; ensure this directory is empty and has necessary space before starting trace. 1.Start trace: strmqtrc t all t detail m QMGRNAME 2.Then recreate failure/problem 3.Stop tracing: endmqtrc a 4.cd to /var/mqm/trace directory and issue command dspmqtrc *.TRC to format files. 5.Send formatted *.FMT trace files to us. If error is before qmgr startup, can instead use strmqtrc e option which is not qmgr specific and capture every MQ process MQ trace directions can be found at this website: http://www-01.ibm.com/support/docview.wss?rs=171&uid=swg21174924

WebSphere Support Technical Exchange

40 of 43

IBM Software Group

Additional WebSphere Product Resources

Learn about upcoming WebSphere Support Technical Exchange webcasts, and access previously recorded presentations at: http://www.ibm.com/software/websphere/support/supp_tech.html Discover the latest trends in WebSphere Technology and implementation, participate in technically-focused briefings, webcasts and podcasts at: http://www.ibm.com/developerworks/websphere/community/ Join the Global WebSphere User Group Community: http://www.websphere.org Access key product show-me demos and tutorials by visiting IBM Education Assistant: http://www.ibm.com/software/info/education/assistant View a webcast replay with step-by-step instructions for using the Service Request (SR) tool for submitting problems electronically: http://www.ibm.com/software/websphere/support/d2w.html Sign up to receive weekly technical My Notifications emails: http://www.ibm.com/software/support/einfo.html

WebSphere Support Technical Exchange

41 of 43

IBM Software Group

We Want to Hear From You!

Tell us about what you want to learn
Suggestions for future topics Improvements and comments about our webcasts We want to hear everything you have to say!
Please send your suggestions and comments to: wsehelp@us.ibm.com

WebSphere Support Technical Exchange

42 of 43

IBM Software Group

Questions and Answers

WebSphere Support Technical Exchange

43 of 43