3.1.5.8.9 Sending a Trace Message

If the UserMessage.BaseHeader.Flags.TR bit field is set, the protocol MUST send a report message to the queue specified by the UserMessage.DebugHeader.QueueIdentifier field. Report messages are utilized by application logic to track the delivery of sent messages.

To send a report message, the protocol MUST construct a new Message ADM element instance ([MS-MQDMPR] section 3.1.1.12), referred to as TraceMessage, and MUST set the following attributes:

  • TraceMessage.Class is set to Report.

  • TraceMessage.DestinationQueueFormatName is set to a public format name ([MS-MQMQ] section 2.1.3) constructed using the GUID in the DebugHeader.QueueIdentifier field.

  • TraceMessage.DeliveryGuarantee is set to Express.

  • TraceMessage.Label is set to a Unicode string in the format specified by the following ABNF rules.

     label = qm-id %x3A message-id %x3A hops SP "received by" SP computer 
             SP "at"  SP time-date %x0000
     qm-id = 4HEXDIG ; MUST be set to the first four hexadecimal digits 
                     ; of the source queue identifier
     message-id = 8HEXDIG ; hexadecimal form of the UserHeader.MessageID
                          ; field
     hops = 2HEXDIG ; MUST be set to the UserHeader.Flags.RC field
     computer = GUID ; MUST be set to UserHeader.SourceQueueManager field
     time-date = hour SP ("AM" / "PM") SP date
     hour  =  2DIGIT ":" 2DIGIT [":" 2DIGIT] ; ANSI and Military
     date =  day "," month SP 2DIGIT SP year; day, month day year
     month  = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun"
              / "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"
     day = "Mon" / "Tue" / "Wed" / "Thu" / "Fri" / "Sat" / "Sun"
     year = 2DIGIT
     GUID =  8HEXDIG "-" 4HEXDIG "-" 4HEXDIG "-" 4HEXDIG "-" 12HEXDIG 
             ; A GUID the form XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX 
             ; Where each X is a Hex digit
      
    
  • TraceMessage.Body is set to a Unicode string in the format specified by the following ABNF rules.

      
      
     Report = "<MESSAGE ID>" id "</MESSAGE ID>" CR LF
              "<TARGET QUEUE>" queue "</TARGET QUEUE>" CR LF
     id = 8HEXDIG ; MUST be set to UserHeader.MessageID field
     queue = queue-format; MUST be set to UserHeader.DestinationQueue field
      
    

The ABNF rule queue-format is as specified in [MS-MQMQ] section 2.1.

The protocol MUST generate an Open Queue ([MS-MQDMPR] section 3.1.7.1.5) event with the following arguments:

  • iFormatName := TraceMessage.DestinationQueueFormatName

  • iRequiredAccess := QueueAccessType.SendAccess

  • iSharedMode := QueueShareMode.DenyNone

If the rStatus returned by the Open Queue event is not MQ_OK (0x00000000), the protocol MUST discard TraceMessage; otherwise, the protocol MUST generate an Enqueue Message To An Open Queue ([MS-MQDMPR] section 3.1.7.1.27) event with the following arguments:

  • iOpenQueueDescriptor := the rOpenQueueDescriptor returned by the Open Queue event

  • iMessage := TraceMessage