The broker provides basic error handling for all your message
flows. If basic processing is not sufficient, and you want to take specific
action in response to certain error conditions and situations, you can enhance
your message flows to provide your own error handling. For
example, you might design a message flow that expects certain errors that
you want to process in a particular way, or a flow that updates a database
and must roll back those updates if other processing does not complete successfully.
The
options that you can use to do this are quite complex in some cases. The options
that are provided for MQInput
and TimeoutNotification nodes are extensive because these nodes deal
with persistent messages and transactions. MQInput is also affected by configuration options for WebSphere MQ.
Because you can decide to handle
different errors in different ways, there are no fixed procedures to describe.
This section provides information about the principles of error handling,
and the options that are available, and you must decide what combination of
choices that you need in each situation based on the details that are provided
in this section.
You can choose one or more of these options in your
message flows:
- Connect the failure terminal of any node to a sequence of nodes that processes
the node's internal exception (the fail flow).
- Connect the catch terminal of the input node or a TryCatch
node to a sequence of nodes that processes exceptions that are generated
beyond it (the catch flow).
- Insert one or more TryCatch nodes at specific points in the
message flow to catch and process exceptions that are generated by the flow
connected to the try terminal.
- Include a Throw node, or code an ESQL THROW statement, to
generate an exception.
- If you are using aggregation, connect the catch terminal
of the AggregateReply node to process aggregation exceptions.
- Ensure that all messages received by an MQInput node are processed within a transaction, or are not.
- Ensure that all messages received by an MQInput node are persistent, or are not.
If you include
user-defined nodes in your message flow, you must refer to the information
provided with the node to understand how you might handle errors with these
nodes. The descriptions in this section cover only the built-in nodes.
When
you design your error handling approach, consider the following factors:
- Most of the built-in nodes have failure terminals. The exceptions are AggregateControl. AggregateRequest, Input, Label, Output,
Passthrough, Publication, Real-timeInput, Real-timeOptimizedFlow, Throw, Trace, and TryCatch.
When
an exception is detected within a node, the message and the exception information
are propagated to the node's failure terminal. If the node does not have a
failure terminal, or it is not connected, the broker throws an exception and
returns control to the closest previous node that can process
it. This might be a TryCatch node, an AggregateReply node, or the input
node.
If an MQinput node detects
an internal error, its behavior is slightly different; if the failure terminal
is not connected, it attempts to put the message to the input queue's backout
requeue queue, or (if that is not defined) to the dead letter queue of the
broker's queue manager,
For more information, see the following:
- A small number of built-in nodes have catch terminals.
These are AggregateReply, HTTPInput, MQInput,
SCADAInput, JMSInput, JMSOutput, TimeoutNotification, and TryCatch.
A message is propagated to a catch terminal only if it has
first been propagated beyond the node (for example, to the nodes connected
to the out terminal).
- When a message is propagated to the failure or catch terminal, the node
creates and populates a new ExceptionList with an exception that represents
the error that has occurred. The ExceptionList is propagated as part of the
message tree.
- The MQInput
and TimeoutNotification nodes have additional processing for transactional
messages (other input nodes do not handle transactional messages).
For more information, see the following topics:
- If you include a Trace node that specifies $Root or $Body,
the complete message is parsed. This might generate parser errors that are
not otherwise detected.
The general principles of error handling are:
- If you connect the catch terminal of the input node, you are indicating
that the flow handles all exceptions that are generated anywhere in the out
flow. The broker performs no rollback and takes no action unless there is
an exception on the catch flow. If you want any rollback action after an exception
has been raised and caught, you must provide this in the catch flow.
- If you do not connect the catch terminal of the MQInput or
HTTPInput node, you can connect the failure terminal and provide a fail
flow to handle exceptions generated by the node. The fail flow is invoked
immediately when an exception occurs in the node.
The fail flow is also
invoked if an exception is generated beyond the MQInput node (in either out or catch flows), the message is transactional,
and the reinstatement of the message on the input queue causes the backout
count to reach the backout threshold.
The HTTPInput and
SCADAInput nodes do not propagate the message to the failure terminal if an
exception is generated beyond the node and you have not connected the catch
terminal.
- If a node propagates a message to a catch flow, and another exception
occurs that returns control to the same node again, the node handles the message
as though the catch terminal is not connected.
- If you do not connect either failure or catch terminals of the input node,
the broker provides default processing (which varies with the type of input
node).
- If you need a more comprehensive error and recovery approach,
include one or more TryCatch nodes to provide more localized areas of error
handling.
- If you have a common procedure for handling particular errors, you might
find it appropriate to create a subflow that includes the sequence of nodes
required. Include this subflow wherever you need that action to be taken.
For more information, see the following topics:
If your message flows include database updates, the way
in which you configure the nodes that interact with those databases can also
affect the way that errors are handled:
- You can specify whether updates are committed or rolled back. You can
set the node property Transaction to
specify whether database updates are committed or rolled back with the message
flow (option Automatic)
or committed or rolled back when the node itself terminates (option Commit). You must ensure that the
combination of these property settings and the message flow error processing
give the correct result.
- You can specify how database errors are handled. You can set the properties Treat warnings as errors and Throw exception on database error to
change the default behavior of database error handling.
For more information about coordinated database updates,
see Configuring message flow transactions.
Message flows for
aggregation involve additional considerations that are not discussed in this
section; these are described in Handling exceptions in aggregation flows.
The Error Handler sample demonstrates how to use an error
handling routine to trap information about errors and to store that information
in a database. The error handling routine is a subflow that you can add,
unchanged, to any message flow. The sample also demonstrates how to configure
message flows to control transactionality; in particular, the use of globally
coordinated transactions to ensure overall data integrity.