IBM Support recently released a Support Doc which was titled:-
Finding the reason why a message was sent to the Dead Letter Queue (DLQ) in IBM MQ
The document described several options, which often required you to look at the message in hex and, when required, byte swap the value to find the reason code. In this post we cover how to do this using MQGem tools as several of them offer this capability, and our tools format out the Dead Letter Header so you don’t need to do any manual byte swapping. Open up the twisty for each tool to read how to do this.
In MO71 you can browse the messages on the Dead Letter queue using a Message List. If you choose to show the “Message Summary” column on your list dialog (see Configuring List Dialogs in MO71 for how to change the columns in a list dialog), you will immediately be able to see the reason code in the Dead-Letter header, as that is one of the useful things that Message Summary displays look for.
Alternatively you can double click on a message to look at the full details of an individual message, and you will see the full Dead-Letter header (MQDLH) is formatted out for you to see.
Using the Q program
To view your messages on the Dead Letter queue, and have them formatted out, you need to use the -df option which also has three levels of detail. For full detail use -df3. Here’s an example command:-
q -m MQG1 -i MQG1.DEAD.LETTER.QUEUE -df3
Which will format the Dead Letter header like this making it really easy to understand the reason why the message was placed on the DLQ.
[ 181 bytes] Message Content [ 181 bytes] Dead Letter Queue Header (MQDLH) StrucId :'DLH ' Version :1 Reason :2085 (Unknown object name) Dest. Queue :'TARGET.QUEUE ' Dest. QMgr :'MQG1 ' MQEncoding :0x'222' (Reversed) CCSID :437 (IBM PC) Format :'MQSTR ' (String) PutApplType :11 (Windows NT) PutApplName :':\mqm9250\bin64\amqrmppa.exe' Put Date :'20220411' Put Time :'05021009' Some text
When you look at the messages on a queue using MQEdit, the message list will show you a summary of the message in the “Message” column, which for Dead Letter header messages will show you the reason from the header. This makes it very easy to see the reasons why messages are on your Dead Letter queue.
Selecting a message from the list will display it in the pane below with the Dead Letter header formatted out also showing you the reason why the message ended up on the DLQ.
Using QLOAD (honourable mention)
QLOAD isn’t a message formatting tool, so it will not help you to view the reason code in the Dead Letter header of a message. However, it does get an honourable mention in this list because it can help you to move, or unload messages from your Dead Letter queue that have a specific reason code in the Dead Letter header. This can be very helpful if you want to siphon off some specific errors to handle in a different way.
Use a command like this to copy (-i is browse) all the DLQ messages for MQRC_UNKNOWN_OBJECT_NAME (2085) to a file.
qload -m MQG1 -i MQG1.DEAD.LETTER.QUEUE -Gr:2085 -fUnknownObjs.qld
When you’re using this feature, QLOAD will report the message selection that you have active:-
Message selection active: Messages with DLQ Reason 2085 Unknown object name Read - Files: 0 Messages: 3 Bytes: 5616 Written - Files: 1 Messages: 1 Bytes: 181
If you don’t have any of these tools, but would like to try any or all of them out, please contact email@example.com and a 1-month trial licence will be sent to you with no obligation to buy. You can download the tools from our website.