Dead Letter Header in sample message browser

MQ 9.3.4 enhanced one of the most commonly-used sample programs, the message browser. It shows some additional statistics, and decodes the dead letter header.

I got fed up with answering the question – why is this message on the dead letter queue. I had been asked the same thing several times within a week. And my answer had been – look at the DLH. There are a number of reasons why a message might end up there, but one key piece of evidence is in the Dead Letter Header on the front of the message.

If you look in the product documentation, you’ll find pages like this one, that tell you to use the amqsbcg sample to review that header. Except you would have to know which offsets in the message contain useful information such as the Reason code.

****   Message      ****

 length - 333 of 333 bytes

00000000:  444C 4820 0000 0001 0000 07F3 4445 5354 'DLH .......□DEST'
00000010:  2E51 5545 5545 0000 0000 0000 0000 0000 '.QUEUE..........'
00000020:  0000 0000 0000 0000 0000 0000 0000 0000 '................'
00000030:  0000 0000 0000 0000 0000 0000 4445 5354 '............DEST'
00000040:  2E51 4D47 5200 0000 0000 0000 0000 0000 '.QMGR...........'
00000050:  0000 0000 0000 0000 0000 0000 0000 0000 '................'
00000060:  0000 0000 0000 0000 0000 0000 0000 0111 '................'
00000070:  0000 0333 4D51 4852 4632 2020 0000 0000 '...3MQHRF2  ....'
00000080:  4120 476F 2070 726F 6772 616D 0000 0000 'A Go program....'
00000090:  0000 0000 0000 0000 0000 0000 3230 3233 '............2023'
000000A0:  3132 3133 3134 3030 3436 0000 5246 4820 '1213140046..RFH '
...

Without looking at the definition of the MQDLH structure, and knowing how long each field is, there’s no clue as to where to look. Here, it’s the 000007F3 starting at offset 8 which decodes to MQRC_NOT_AUTHORIZED. It helps that I ran this particular test on a big-endian machine, otherwise I’d also have to know to byte-reverse the word.

Decoding the DLH

This irritated me, so I ended up changing the sample program. In fact I had to change 3 variants of the same program – we have amqsbcg, amqsbcg4 and csqbcg depending on which platform you use. The output differs slightly in each case, because of how the programs are built. But the core part of the code is the same.

The output from the browser sample now looks like this:

MQGET of message number 2, CompCode:0 Reason:0
****Message descriptor****

  StrucId  : 'MD  '  Version : 2
  Report   : 0  MsgType : 4
  Expiry   : -1  Feedback : 0
  Encoding : 273  CodedCharSetId : 819
  Format : 'MQDEAD  '
  ...
 
****Dead Letter Header****

  StrucId  : 'DLH '  Version : 1
  Reason   : 2035 [MQRC_NOT_AUTHORIZED]
  DestQName      : 'DEST.QUEUE'
  DestQMgrName   : 'DEST.QMGR'
  Encoding : 273  CodedCharSetId : 819
  Format : 'MQHRF2  '
  PutApplType    : '0'
  PutApplName    : 'A Go program'
  PutDate  : '20231213'    PutTime  : '140046'

****   Message      ****
length - 161 of 161 bytes

00000000:  5246 4820 0000 0002 0000 0074 0000 0111 'RFH .......t....'
00000010:  0000 0333 4D51 5354 5220 2020 0000 0000 '...3MQSTR   ....'
00000020:  0000 04B8 0000 004C 3C75 7372 3E3C 434F '...□...L<usr><CO'
00000030:  4C4F 5552 3E47 5245 454E 3C2F 434F 4C4F 'LOUR>GREEN</COLO'
...

This particular example shows an RFH2 in the message body. The sample already has an option to decode it as message properties; I chose not to use that for this test run.

Browser Statistics

At the same time as I was adding the DLH-decoder, Jon was adding statistics to the same programs. After browsing all the messages and coming to the end of the queue, the sample prints some data about all the messages in that run. I find the message count particularly useful for some of my tests – it’s a quick way to ensure that all the messages I expected to see on a queue have arrived.

 No more messages

****   Summary      ****
 4 messages browsed.
 Smallest message 12 bytes.
 Largest message 333 bytes.
 Average message 162 bytes.

Summary

The sample programs are primarily to demonstrate various features of the MQI to help you write your own applications. But they get used for a lot more than that. Putting more features into these samples reduces the need to modify them or write your own versions. I’ve already found these enhancements useful in my regular work.

This post was last updated on December 14th, 2023 at 12:46 pm