Viewing the logical message tree in trace output

To view the structure of the logical message tree at any point in the message flow, include a Trace node and write some or all of the message (including headers and all four message trees) to the trace output destination.

You might find this useful to check or record the content of a message before and after a node has made changes to it, or on its receipt by the input node. For example, if you include a Compute node that builds a destination list in LocalEnvironment, you might want a record of the structure that it has created as part of an audit trail, or you might just want to check that the Compute node is working as you expect it to.

  1. Switch to the Broker Application Development perspective.
  2. Open the message flow for which you want to view messages. This can be an existing message flow, or you can create a new message flow.
  3. Include a Trace node wherever you want to view part or all of the message tree structure. There is no limit to the number of Trace nodes that you can include, however each node introduces some overhead to the message flow processing.
  4. Set the Trace node properties to trace the message, or parts of the message, that you want to view. You specify the parts of the message using ESQL field references. Several examples are included below.
  5. If you have added a Trace node to investigate a particular behavior of your message flow, and have now resolved your concerns or checked that the message flow is working correctly, remove the Trace node or nodes, and redeploy the message flow.

Assume that you have configured a message flow that receives an XML message on a WebSphere MQ queue in an MQInput node. The input message includes an MQRFH2 header. The message content is shown below:

<Trade type='buy'
 Company='IBM'
 Price='200.20'
 Date='2000-01-01'
 Quantity='1000'/>

You can include and configure a Trace node to produce output that shows one or more of the trees created from this message: the message body, Environment, LocalEnvironment, and Exception trees. If you choose to record the content of the message body, the Properties tree and the contents of all headers (in this example, at least an MQMD and an MQRFH2) are included. You specify what you want to be recorded when you set the Trace node property Pattern. You can use most of the correlation names to define this pattern (you cannot use those names that are specific to the Compute node).

Message body
If you want the Trace node to write the message body tree including Properties and all headers, set Pattern to $Root. If you want only the message data, set Pattern to ${Body}.

The trace output generated for the message tree of the message shown above with Pattern set to $Root would look something like:

Root
      Properties
         CreationTime=GMTTIMESTAMP '1999-11-24 13:10:00'          (a GMT timestamp field)
 
  ... and other fields ...
 
      MQMD
         PutDate=DATE '19991124'                                  (a date field)
 
         PutTime=GMTTIME '131000'                                 (a GMTTIME field)
 
  ... and other fields ...
 
      MQRFH
          mcd
          msd='xml'                                              (a character string field)
 
         .. and other fields ...
 
      XML
         Trade
          type='buy'                                             (a character string field)
 
         Company='IBM'                                           (a character string field)
 
         Price='200'                                             (a character string field)
 
         Date='2000-01-01'                                       (a character string field)
 
         Quantity='1000'                                         (a character string field)
Environment
To trace any data in the environment tree, set Pattern to ${Environment}. This produces output similar to the following:
 (0x1000000)Environment = (
      (0x1000000)Variables = (
        (0x1000000)MyVariable1 = (
          (0x2000000) = '3'
        )
        (0x1000000)MyVariable2 = (
          (0x2000000) = 'Hello'
        )
      )
  ) 

To trace particular variables in the variables folder of the environment tree, you can use a more specific pattern, for example ${Environment.Variables.MyVariable1}. This returns the value only (for example, it returns just the value 3).

LocalEnvironment
To trace data in the LocalEnvironment tree, set Pattern to ${LocalEnvironment}. The output you get is similar to the following example, which shows that a destination list has been created within the LocalEnvironment tree:
(0x1000000)Destination = (
    (0x1000000)MQ                = (
      (0x1000000)DestinationData = (
        (0x3000000)queuename = 'MQOUT'
      )
    )
     (0x1000000)MQDestinationList = (
      (0x1000000)DestinationData = (
        (0x3000000)queuename = 'OLDMQOUT'
      )
    )
    (0x1000000)RouterList        = (
      (0x1000000)DestinationData = (
        (0x3000000)labelname = 'continue'
      )
      (0x1000000)DestinationData = (
        (0x3000000)labelname = 'custdetails'
      )
      (0x1000000)DestinationData = (
        (0x3000000)labelname = 'trade'
      )
    )
  )      

Another example, shown below, includes a WrittenDestination folder. This represents a trace that has been written by a Trace node included after an MQOutput node, where the out terminal of the MQOutput node is connected to a sequence of nodes including the Trace node. When an out terminal is connected, the LocalEnvironment is augmented with information about the action that the output node has performed.

(0x1000000)Destination        = (
    (0x1000000)MQ                = (
      (0x1000000)DestinationData = (
        (0x3000000)queuename = 'MQOUT'
      )
    )
  (0x1000000)WrittenDestination = (
    (0x1000000)MQ = (
      (0x1000000)DestinationData = (
        (0x3000000)queueName        = 'MQOUT'
        (0x3000000)queueManagerName = 'MQSI_SAMPLE_QM'
        (0x3000000)replyIdentfier   = X'414d51204d5153495f53414d504c455f1f442f3b12600100'
        (0x3000000)msgId            = X'414d51204d5153495f53414d504c455f1f442f3b12600100'
        (0x3000000)correlId         = X'000000000000000000000000000000000000000000000000'
      )
    )
  )
)
ExceptionList
To trace data in the exception list, set Pattern to ${ExceptionList}.

You can also view message structure within the message flow, and other information, when you use the flow debugger.

Related concepts
Message flows overview
Logical tree structure
Correlation names
Flow debugger
Related tasks
Designing a message flow
Manipulating message body content
Manipulating other parts of the message tree
Testing and debugging message flow applications
Related reference
Trace node
Exception list structure