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 the message (including headers and all four message trees) to the trace output destination.

About this task

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

Procedure

  1. Switch to the Integration Development perspective.
  2. Open the message flow for which you want to view messages.
    Open an existing message flow, or create a message flow.
  3. Include a Trace node wherever you want to view part or all the message tree structure.
    You can include as many Trace nodes as you choose; however, each node that you introduce can affect the performance of message flow processing.
  4. Set the Trace node properties to trace the message, or parts of the message, that you want to view.
    Specify the parts of the message by using ESQL field references. Several examples are included later in this topic.
  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.

Example

Assume that you have configured a message flow that receives an XML message on a IBM® MQ queue in an MQInput node. The input message includes an MQRFH2 header. The message has the following content:

<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, local environment, 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 preceding message with Pattern set to ${Root} would look like the following example:

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 setting produces output like the following example: 
 (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 setting returns the value only (for example, it returns just the value 3).

LocalEnvironment
To trace data in the local environment tree, set Pattern to ${LocalEnvironment}. The output you get is like the following example, which shows that a destination list has been created in the local environment 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 here, includes a WrittenDestination folder. This example represents a trace that has been written by a Trace node that is 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 local environment 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'
        (0x03000000):GroupId          = X'414d512042524f4b45523220202020203f59934620001803'
        (0x03000000:NameValue):bindingType             = 'CLIENT' (CHARACTER)
        (0x03000000:NameValue):destinationQueueManager = 'QM1_REG1' (CHARACTER)
        (0x03000000:NameValue):queueManagerHostname    = 'MYQUEUEMANAGERHOSTNAME' (CHARACTER)
        (0x03000000:NameValue):listenerPortNumber      = 9000 (INTEGER)
        (0x03000000:NameValue):channelName             = 'MYCHANNELNAME' (CHARACTER)
      )
    )
  )
)
ExceptionList
To trace data in the exception list, set Pattern to ${ExceptionList}.

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