Exploiting user exits

Your message flows can benefit from user exits.

Before you start:

Start of changeThe following diagram illustrates how a user exit works. The numbered events are described after the diagram. The MQInput node is used as an example, but the function applies to all input nodes, including user-defined input nodes. Similarly, the Compute and MQOutput nodes could be replaced by any equivalent nodes.End of change

Basic message flow events
Start of change
  1. The message is dequeued from the input source (read into the flow).

    Built-in nodes and user-defined nodes differ slightly in the way in which user exits are called. For built-in input nodes, the user exit is called 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.

  2. The message is propagated to the node for processing.
  3. Node processing completes.
  4. The user exit is invoked after the transaction has completed, so user exit processing is not part of that transaction. The user exit is called even if no transactional processing is completed by the flow.

    Where the message flow property Commit Count is greater than one, many-to-one ratios exist between events 1 and 4. This ratio also exists for some scenarios that are specific to the particular input node; for example, when an MQInput node is configured with the Commit by Message Group property selected.

End of change
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:
  • The message is dequeued:
    • Bit stream
    • Input node
    • Environment tree (read and write)
  • The message is propagated to the node:
    • Message tree
    • LocalEnvironment tree (read and write)
    • Exception list
    • Environment tree (read and write)
    • Source node
    • Target node
  • Node processing completes:
    • Message tree
    • LocalEnvironment tree (read and write)
    • Exception list
    • Environment tree (read and write)
    • Node
    • Upstream node
    • Exception (if any)
  • The end of the 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 that are made to the message assembly (the message and environment) 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 user exit can also perform the following tasks:
  • Navigate and read the message assembly (Message, LocalEnvironment, ExceptionList)
  • Navigate and read or write the Environment tree

You can register the user exits 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
User-defined extensions
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2009Copyright IBM Corporation 1999, 2009.
Last updated : 2009-01-07 15:19:59

ac02145_