Add more header decoding

Author: ibmmqmet

CHANGELOG.md

@@ -2,6 +2,12 @@
 # Changelog
 Newest updates are at the top of this file.
 
+## 202x xxx xx - V2.0.1
+* MQXQH 
+  - get_header() function to extract structure (#4)
+  - get_embedded_md() function
+* Added MQMDE class for if you want to parse MQXQH messages
+
 ## 2025 Oct 16 - V2.0.0
 * First production release, based on MQ 9.4.4
 * Fix SETMP/INQMP problem found in beta

code/examples/README.md

@@ -31,6 +31,7 @@ You might need to change these assumptions in the examples for your own queue ma
   * async_consume
   * inq_set
   * dlq_browse
+  * hdr_browse
   * channel_compression
   * message_priority
   * message_properties

code/examples/hdr_browse.py

@@ -0,0 +1,124 @@
+# More examples are at https://github.com/ibm-messaging/mq-dev-patterns
+# and in code/examples in the source distribution.
+
+"""
+This example browses a queue, formatting any known MQ header structures that it finds. It is
+an extension to the DLH example, in that it deals with a number of other headers
+including the XQH found on messages on transmission queues.
+"""
+
+import ibmmq as mq
+from ibmmq import CMQC
+
+queue_manager = 'QM1'
+channel = 'DEV.ADMIN.SVRCONN'
+host = '127.0.0.1'
+port = '1414'
+conn_info = '%s(%s)' % (host, port)
+user = 'admin'
+password = 'password'
+
+qmgr = mq.connect(queue_manager, channel, conn_info, user, password)
+
+ok = True
+
+od = mq.OD()
+# This is an XMITQ associated with a STOPPED channel, because we want to look at XQH processing
+od.ObjectName = 'QM2.STOPPED'
+
+q = mq.Queue(qmgr, od, CMQC.MQOO_BROWSE)
+
+gmo = mq.GMO()
+gmo.Options = CMQC.MQGMO_BROWSE_FIRST
+cnt = 1
+
+while ok:
+    try:
+        md = mq.MD()
+        msg = q.get(None, md, gmo)
+
+        print('------------------------------------')
+        print(f"Message: {cnt}")
+        cnt += 1
+
+        gmo.Options = CMQC.MQGMO_BROWSE_NEXT
+        fmt = md['Format']
+
+        headers = True
+        offset = 0
+        ccsid = md['CodedCharSetId']
+
+        # Iterate through headers that we might expect to see until there are no more.
+        while headers:
+            print()
+            print('------------')
+            print(f'Header: {bytes.decode(fmt, "utf8")}')
+            print('------------')
+
+            if fmt == CMQC.MQFMT_XMIT_Q_HEADER:
+                # The XQH definition in Python has only the first part of the XQH in C, with the
+                # embedded MQMD excluded. But We can extract both parts explicitly with XQH methods.
+                xqh = mq.XQH().get_header(msg)
+                print(xqh.to_string())
+
+                # The to_string method changes structure contents, so we first stash the
+                # Format in its bytes version. That matches the CMQC definition as a bytes-string.
+                emd = mq.XQH().get_embedded_md(msg)
+                fmt = emd['Format']
+                ccsid = emd['CodedCharSetId']
+                # print(f'G = {emd['GroupId']}')
+
+                print()
+                offset += CMQC.MQXQH_CURRENT_LENGTH
+
+                print(emd.to_string())
+
+            elif fmt == CMQC.MQFMT_MD_EXTENSION:
+                # This will only be seen when looking at transmission queues with the XQH block
+                mde = mq.MDE().unpack(msg[offset:offset + CMQC.MQMDE_CURRENT_LENGTH])
+                fmt = mde['Format']
+                ccsid = mde['CodedCharSetId']
+                offset += CMQC.MQMDE_CURRENT_LENGTH
+
+                print(mde.to_string())
+
+            elif fmt == CMQC.MQFMT_RF_HEADER_2:
+                rfh2 = mq.RFH2()
+                rfh2.unpack(msg[offset:], 'utf8')
+                fmt = rfh2['Format']
+                offset += rfh2['StrucLength']
+
+                print(rfh2.to_string())
+
+            elif fmt == CMQC.MQFMT_DEAD_LETTER_HEADER:
+                dlh = mq.DLH()
+                dlh.unpack(msg[offset:offset + CMQC.MQDLH_CURRENT_LENGTH])
+                fmt = dlh['Format']
+                ccsid = dlh['CodedCharSetId']
+                offset += CMQC.MQDLH_CURRENT_LENGTH
+
+                print(dlh.to_string())
+
+            else:
+                headers = False
+
+        # And now print the message body. Strings get converted, otherwise just print bytes
+        print()
+        print('Message Body:')
+
+        if fmt == CMQC.MQFMT_STRING:
+            cp = 'utf8'  # Assume a codepage, though we might want to use the ccsid to be more discriminating
+            print(bytes.decode(msg[offset:], cp))
+        else:
+            print(msg[offset:])
+
+        print()
+
+    except mq.MQMIError as e:
+        if e.reason == CMQC.MQRC_NO_MSG_AVAILABLE:
+            print('No more messages.')
+            ok = False
+        else:
+            raise
+q.close()
+qmgr.disconnect()

code/ibmmq/mqadmin.py

@@ -391,12 +391,19 @@ def __init__(self, name=None,
         self.__command_queue_name = command_queue_name
 
         self.__convert = convert
+
+        # Don't allow Unlimited waits. Force it to something large, but
+        # not forever. This gives an hour. Setting it to zero would also be foolish,
+        # as there would be no time at all to wait for the response. But we'll allow you to
+        # find that for yourself.
+        if response_wait_interval < 0:
+            response_wait_interval = 60 * 60 * 1000  
         self.__response_wait_interval = response_wait_interval
 
         if model_queue_name and reply_queue_name:
             raise PYIFError('Do not specify both a model_queue_name and a reply_queue_name')
 
-        # From here, we can treat the 2 qnames as equivalent. So assign to one and use it
+        # From here, we can treat the 2 qnames as equivalent. So assign to one and use it.
         # There is an internal __reply_queue_name field, but that comes from the result of the
         # MQOPEN - gives the TDQ name if that's been created.
         if reply_queue_name:

code/ibmmq/mqopts.py

@@ -249,6 +249,27 @@ def __getitem__(self, key: str) -> Any:
         """
         return getattr(self, key)
 
+    def _remove(self, key: str) -> None:
+        """Remove an attribute from the object. Not meant for general use.
+        This removes both the attribute and knowledge about how it is formatted
+        """
+        # Have to convert tuples into a list so it can be modified
+        l = list(self.__list)
+
+        for item in l:
+            if item[0] == key:
+                l.remove(item)
+                try:
+                     delattr(self,key)
+                except AttributeError:
+                    pass
+                break
+
+        # And then convert back to the tuple format
+        self.__list = tuple(l)
+
+        return
+
     def __str__(self) -> str:
         rv = ''
         for i in self.__list:

code/ibmmq/mqxqh.py

@@ -36,7 +36,8 @@ def get_header(self, buf):
     # Return the MQMD that is part of the real (full) MQXQH structure. It is always
     # an MQMDv1, but this package usually deals with MQMDv2. So we extract the block and add
     # a zero-filled pad array to ensure it's the right length. Which means that the MDv2 fields
-    # (eg GroupId) may not be accurate if the original message was using those MDv2 fields.
+    # (eg GroupId) may not be accurate if the original message was using those MDv2 fields. So we
+    # remove them from the returned MD.
     # If the Format in this MD indicates there is a subsequent MQMDE, which corresponds to
     # the MDv2 fields, then you can extract that and unpack it directly before then
     # continuing on to the rest of the message body.
@@ -46,4 +47,10 @@ def get_embedded_md(self, buf):
         pad = CMQC.MQMD_LENGTH_2 - CMQC.MQMD_LENGTH_1                   # How long is the padding
         md_buf = buf[offset:CMQC.MQXQH_CURRENT_LENGTH] + bytearray(pad)
         md = MD().unpack(md_buf)
+        # Remove the MDv2-specific fields.
+        md._remove('GroupId')
+        md._remove('MsgSeqNumber')
+        md._remove('Offset')
+        md._remove('MsgFlags')
+        md._remove('OriginalLength')
         return md

tools/runAllExamples

@@ -44,6 +44,7 @@ examples=`ls ../code/examples/*py |\
    grep -v "async_consume" |\
    grep -v put_get_correl_id |\
    grep -v publish |\
+   grep -v hdr_browse |\
    grep -v subscribe`
 for testcase in $examples
 do