MQRFH2

MQRFH2 is how IBM MQ carries extra properties on a message without cramming them into the business payload. Integration middleware and JMS clients wrap JSON or XML in a buffer that starts with one or more headers: MQRFH2 folders hold string tags like content type, reply queue hints, trace identifiers, and broker routing instructions. A COBOL program doing plain MQGET sees unfamiliar bytes before the expected copybook—those bytes are often RFH2, not corruption. Publishers on topics may embed RFH2 so subscribers filter on properties. This tutorial explains header layout at a beginner level, common folders (mqmd, mcd, jms, usr), how RFH2 chains with MQMD Format, length calculation on MQPUT, consumer strategies to skip or parse, MQRFH versus obsolete RFH1, and troubleshooting property loss across channels.

Where RFH2 Sits in the Message

A message on the wire and in the queue file logically contains: MQMD (descriptor, separate structure in API), then optional headers (MQRFH2, MQDLH for dead letter, etc.), then application data. In a single MQPUT buffer for header APIs, bytes are concatenated: RFH2 structure followed by payload. MQMD.Format may be MQFMT_RF_HEADER_2 or a string indicating embedded headers per IBM patterns. Total message length on MQPUT includes header plus body. MAXMSGL must accommodate the sum—channels reject oversize totals.

Structure Basics

MQRFH2 starts with StrucId RFH and Version MQRFH_VERSION_2. Flags control parsing. NameValueStringLength and NameValueStringCount describe the property bag. Each property is a length-prefixed name and value in UTF-8 or configured encoding. Building by hand in C requires careful length arithmetic—off-by-one causes 2014 or truncation. JMS setStringProperty becomes RFH2 entries transparently to the developer.

1
2
3
4
5
6
7
Logical layout (conceptual):
 
[ MQMD - separate parameter in MQI ]
[ MQRFH2 block | optional additional headers ]
[ Application payload - JSON, XML, COBOL bytes ]
 
Consumer must know whether RFH2 is present before parsing payload.

Explainer: Sticky Notes on the Package

MQMD is the official shipping label. MQRFH2 is extra sticky notes brokers stick on saying things like "deliver express" or "JMS reply queue name" that are not part of the letter inside the envelope.

JMS and Integration Bus

When Java JMS sends TextMessage, the client typically inserts RFH2 with jms folder fields. IBM App Connect and IIB map message trees to RFH2 for routing nodes. Changing middleware version can add properties—regression test binary layout when upgrading. Request/reply over JMS still uses CorrelId in MQMD; JMSCorrelationID maps to messaging layer.

Publish/Subscribe Properties

Publishers attach user properties for selective subscription matching in advanced scenarios. Subscribers using bare MQI must parse usr folder or use MQ subscription API that exposes properties. Retained publications may include RFH2 metadata surviving restart per topic configuration.

Consuming Without JMS

1. MQGET full message buffer.
2. Inspect MQMD.Format for header indicator.
3. Parse MQRFH2 StrucId and length; walk name-value pairs.
4. Advance pointer by header length to payload start.
5. Deserialize JSON/XML/COBOL from remaining bytes.

Some clients offer MQGET with properties separated—prefer supported API over manual parse when available. MQGMO_PROPERTIES_COMPATIBILITY affects behavior on certain platforms.

RFH1 Versus RFH2

Legacy MQRFH (version 1) appears in old integrations. Modern paths use RFH2 exclusively. Mixing versions across partners causes parse failures—standardize on RFH2 in interface specifications.

Headers and Dead Letter

Messages hitting DLQ may include MQDLH (dead-letter header) describing failure reason in addition to RFH2. Support teams read DLH Reason field plus original MQMD. Do not strip headers when requeueing without understanding discard rules.

Performance and Size

Large property bags inflate every message and CPU on parse. Keep usr properties minimal. Binary payload belongs in body, not duplicated in properties. Monitor channel bytes versus business bytes ratio in capacity planning.

Troubleshooting

• JSON parse error at byte 0 — RFH2 still prefixed; skip header length.
• Property missing at consumer — not set on put or stripped by intermediate broker.
• 2110 message too big — RFH2 + body exceeded MAXMSGL.
• Garbled Unicode — wrong CodedCharSetId in RFH2 string encoding.

Explain Like I'm Five: MQRFH2

MQRFH2 is extra notes on the outside of your letter package telling delivery robots special instructions before they hand you the real letter inside.

Practice Exercises

Exercise 1

Document your interface: does production traffic include RFH2? How do COBOL consumers know?

Exercise 2

List three jms folder properties you would expect from a JMS TextMessage put.

Exercise 3

Why must MAXMSGL include header plus body length?

Frequently Asked Questions

Test Your Knowledge