This topic contains sections marked as revised for this release

WebSphere Message Brokers
File: ac02145_
Writer: Susan Graham

Task topic

This build: July 31, 2007 21:17:02

Exploiting user exits

This topic shows how your message flows can benefit from user exits.

Before you start you must read User exits.

In the diagram below, the MQInput node is used as an example, but the function applies to all input nodes, including user-defined nodes.

Basic message flow  events

Event 1. The message is dequeued from the input source (read into the flow). However, built-in nodes and user-defined nodes differ slightly in the way in which user exits are invoked. For built-in input nodes, the user exit is invoked as soon as possible after the data has been read from the external source. For user-defined input nodes, the user exit is called just before the node propagates the message.

Event 2. The message is propagated to the node for processing.

Event 3. The node processing is completed.

Event 4. The user exit is invoked after the transaction has completed, so the user exit processing is not part of that transaction. The user exit is invoked even if no transactional processing was completed by the flow. Where the message flow property Commit Count is greater than 1, many-to-one ratios exist between event 1 and event 4. This ratio also exists for some scenarios specific to the particular input node; for example, when an MQInputNode is configured with the Commit by Message Group property selected.

You can write a user exit to track any number of these events. For each of these events, the following data is available to the user exit. All access is read-only, unless stated otherwise:
  • Dequeue message:
    • Bit stream
    • Input node
    • Environment tree (read and write)
  • Message propagated to node:
    • Message tree
    • LocalEnvironment tree (read/write)
    • Exception list
    • Environment tree (read/write)
    • Source node
    • Target node
  • Node processing completed:
    • Message tree
    • LocalEnvironment tree (read and write)
    • Exception list
    • Environment tree (read and write)
    • Node
    • Upstream node
    • Exception (if any)
  • End of transaction:
    • Input node
    • Exception if any
    • Environment tree (read and write)

You can register multiple user exits, and, if they are registered, they are invoked in a defined order (see mqsichangeflowuserexits command). Any changes made to the message assembly by a user exit are visible to subsequent user exits.

When the user exit is invoked, it can query the following information:
  • Message flow information:
    • Message flow name
    • Broker name
    • Broker's queue manager name
    • Execution group name
    • Message flow's commit count property
    • Message flow's commit interval property
    • Message flow's coordinated transaction property
  • Node information:
    • Node name
    • Node type
    • Terminal name
    • Node properties
The node can also perform the following tasks:
  • Navigate and read the message assembly (Message, LocalEnvironment, ExceptionList)
  • Navigate and read or write the Environment tree

The user exits can be registered on a dynamic basis, without needing to redeploy the configuration.

Related concepts
User exits
Related tasks
Deploying a user exit
Developing a user exit
Related reference
mqsichangeflowuserexits command
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:17:02

ac02145_ This topic's URL is: