The Error Handler sample is based on a scenario where a business that is involved in processing
transactions wants to develop a routine for handling errors.
The sample demonstrates how to use some of the features that are provided in IBM Integration Bus.
Businesses such as banks want to make sure that transactions are processed
once and only once, and that there is a record of any errors.
In the Error Handler sample, you put messages about staff numbers through a message flow
that updates a database with this information.
By putting in a message with an invalid staff number, you can observe how the error handling routine works.
The Error Handler sample demonstrates the following tasks:
How to use an error handling routine to trap information about errors,
and store the information on a WebSphere MQ queue.
The error handler routine that is used in the sample is a subflow that you can add,
unchanged, to any message flow.
How to configure message flows to control transactionality.
In particular, the sample demonstrates the use of globally coordinated transactions
to ensure overall data integrity, which is the default mode of operation on z/OS.
On distributed platforms, global coordination requires specific configuration steps,
and is implemented by using the XA protocols.
In this sample, the main message flow in the sample updates a database
with information about staff numbers.
The error handling subflow outputs any messages where processing errors have occurred to a queue.
The database update in the main flow is under transactional control so that if an error occurs,
and the message is processed by the error handling subflow,
the database update about the staff number is rolled back and not committed.
The queue update in the error handler subflow is outside transactional control to
ensure that information about errors is not rolled back,
because the information must be committed to provide a record of errors.
The messages
Two input messages are supplied for running the Error Handler sample:
A message that contains a valid staff serial number
A message that contains an invalid staff serial number
The valid staff message is shown in the following XML code:
The following diagram shows the main message flow.
The following diagram shows the error handling subflow.
The following table lists the types of nodes that are used in the Error Handler sample.
The Subflow node is not technically a node and it is not available in the node palette;
the Subflow node represents where the subflow, Error_Handler.msgflow,
is called within the main message flow.
When you put the valid staff message on the input queue
the message travels through the nodes.
If any of the queues are disabled, the message cannot follow this path.
In the main message flow:
STAFF_IN node. This node gets the input message from the input queue.
Error_Handler node. This node represents the error handling subflow.
The message leaves the main message flow, and enters the subflow.
In the subflow:
Start Subflow node. The message is passed to the next node in the flow.
Check Backout Count node. This node checks whether the backout count is zero.
Because it is the first time that the input message is passed through this node,
the count is currently zero, and the message is passed to the next node.
If the count is more than zero, the message is discarded.
TryCatch node. Because the staff number is valid,
the message is passed to the Back To Main Flow node.
If the staff number in the message is invalid
and the processing of the message has discovered this invalid staff number,
the message is passed to the Copy Message and STAFF_UPDATE_ERROR node.
Back To Main Flow node. The message leaves the subflow and returns to the main message flow.
In the main message flow:
Check Valid Staff Number node. Because the staff number is valid,
the message is passed to the Update Staff Database node.
Update Staff Database node. The STAFFDB database is updated with the staff details in the message.
STAFF_OUT node. This node puts the message on the STAFF_OUT queue.
If you do not have a database, the message is still put onto the queue through the Failure terminal.
This scenario demonstrates this sample without the use of a database and must not be used in production.
The route taken by the invalid staff message
When you put the invalid staff message on the input queue,
the message travels through the nodes as described later in this section.
If any of the queues are disabled, the message cannot follow this path.
For more information about what each node does, see
Built-in nodes
in the IBM Integration Bus documentation.
In the main message flow:
STAFF_IN node. This node gets the input message from the input queue.
Error_Handler node. This node represents the error handling subflow.
The message leaves the main message flow, and enters the subflow.
In the subflow:
Start Subflow node. The message is passed to the next node in the flow.
Check Backout Count node. This node checks whether the backout count is zero.
Because this is the first time that the input message passes through this node,
the count is currently zero, and the message is passed to the next node.
Compare to step 5b later in this section.
TryCatch node. The staff number in the message is invalid, but this has not yet been discovered.
The input message is passed to the Back To Main Flow node, rather than to the STAFF_UPDATE_ERROR node.
Back To Main Flow node. The message leaves the subflow, and returns to the main message flow.
In the main message flow:
Check Valid Staff Number node. Because the staff number is invalid,
the message is passed to the Throw node, rather than to the Update Staff Database node.
Throw node. This node stops the processing of the message
and records the error number "3001", and the text "Invalid staff number"
to the message content.
The message is rolled back, that is, the message is propagated back to the point of control,
which in this case is the TryCatch node in the subflow.
In the subflow:
TryCatch node. This node recognises that an exception has occurred in the processing of the message
and passes the message to the STAFF_UPDATE_ERROR node.
STAFF_UPDATE_ERROR node. The message is sent to the STAFF_UPDATE_ERROR queue.
Throw To Complete Rollback node. This node stops the processing of the message
and records the number "3002", and the text "From Error_Handler message flow."
to the message content. The message is now propagated back to the point of control,
which is the STAFF_IN node in the main message flow.
This stage is the final stage of the catch processing.
It has the effect of rolling back the entire transaction,
including the database updates under transactional control
(that is, the STAFFDB update in the main flow) on the original try path.
However, the STAFF_UPDATE_ERROR update, which is outside transactional control, is still committed.
In the main message flow:
STAFF_IN node. Because an exception has occurred in the processing of the message,
the message is passed to the STAFF_FAIL node, rather than passed through the message flow again.
STAFF_FAIL node. The node puts the message on the STAFF_FAIL queue.
Alternatively, if the STAFF_FAIL queue is disabled, the message does not stop here.
The message is passed back to the STAFF_IN node, and then to the subflow.
The message then reaches the Check Backout Count node, which checks whether the backout count is zero.
Because the message has passed through this node previously the backout count is no longer zero,
and the message is discarded. Discarding the message prevents a situation where,
if the STAFF_FAIL queue is disabled, the message keeps traveling through the flow. Compare this step to step 2b.
When you use a TryCatch node, or when you attach nodes to the Catch terminal of an MQInput node,
you might assume that any processing that has occurred on the try path is not,
if the nodes are correctly configured, committed if the catch path is invoked.
This assumption is not correct.
For example, if a database is updated on the try path under transactional control
and the catch path is invoked and completes normally, the database update is still committed.
The requirement in this sample is to read a message, update a database, and write the message on another queue.
If an error occurs, the database update is rolled back.
Catch processing updates the error database with the details of the error
and writes the original message to the failure queue.
In programming terms, the following example shows what happens:
BEGIN (Start 'outer' unit-of-work.)
MQGET (Get message from the input queue.)
TRY
BEGIN (Start 'inner' unit-of-work.)
Update database
MQPUT (Put message onto the output queue.)
IF ERROR
ROLLBACK inner unit-of-work GO TO CATCH
ELSE
COMMIT inner and outer unit-of-work as one unit-of-work
END IF
CATCH
Send message to STAFF_UPDATE_ERROR queue
MQPUT (Put message onto the failure queue.)
COMMIT outer unit-of-work
However, XA Transaction Manager and WebSphere MQ do not support two levels of
unit-of-work in the same application.
Therefore, the Error Handler sample uses the following structures:
The database, STAFFDB, update in the try path is within transactional control.
The queue, STAFF_UPDATE_ERROR, update in the catch path is outside transactional control.
The Failure terminal of the MQInput node is attached to an MQOutput node, which points to a failure queue.
The final stage of the catch processing is to produce an error again by using a Throw node.
The message then rolls back along the failure path to the MQInput node and,
from there, to the failure queue.
