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 MQeInput and MQInput nodes are extensive because these
nodes deal with persistent messages and transactions. They are 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 MQeInput or MQInput node are processed
within a transaction, or are not.
- Ensure that all messages received by an MQeInput or 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 MQeInput or 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. See MQeInput error handling or MQInput error handling for
further details.
- A small number of built-in nodes have catch terminals.
These are AggregateReply, HTTPInput, MQeInput, MQInput, SCADAInput, 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 MQeInput and MQInput nodes have additional processing for transactional
messages (other input nodes do not handle transactional messages).
- 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 or MQeInput 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.
More details are provided in these 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 nodes for coordinated message flows.
Message
flows for aggregation involve additional considerations that are not discussed
in this section; these are described in Handling exceptions and database deadlocks in aggregation flows.