WebSphere Message Broker, Version 8.0.0.7 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

Handling MQInput errors

The MQInput node takes certain actions when handling errors with persistent and transactional messages. The node attempts retry processing when a transactional message is rolled back to the input queue. Non-transactional messages are not rolled back to the input queue when an exception occurs.

Errors encountered with non-transactional messages are handled as described in Managing errors in the input node.

  • The MQInput node detects an internal error in the following situations:
    • An exception occurs when the associated message parser is initialized. If the Parse timing property is set to Immediate or Complete, the parser parses the input message after initialization. This parsing can cause a parsing or validation error, which is treated as an internal error.
    • A warning is received on an MQGET call.
    • The backout threshold is reached when the message is rolled back to the input queue.
  • If the MQInput node detects an internal error, one of the following actions occur:
    • If you have not connected the Failure terminal, the MQInput node 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. If the put attempt fails, the message is rolled back to the input queue. The MQInput node writes the original error and the MQPUT error to the local error log. The MQInput node now invokes the retry logic, described in Handling retry processing.
    • If you have connected the Failure terminal, you are responsible for handling the error in the flow connected to the Failure terminal. The broker creates a new exception list to represent the error and this is propagated to the Failure terminal as part of the message tree, but neither the MQInput node nor the broker provide any further failure processing.
  • If the MQInput node has successfully propagated the message to the out terminal and an exception is thrown in the out flow, the message is returned to the MQInput node:
    • If you have not connected the Catch terminal, the message is rolled back to the input queue. The MQInput node writes the error to the local error log and invokes the retry logic, described in Handling retry processing.
    • If you have connected the Catch terminal, you are responsible for handling the error in the flow connected to the Catch terminal. The broker creates a new exception list to represent the error and this list is propagated to the Catch terminal as part of the message tree, but neither the MQInput node nor the broker provide any further failure processing.
  • If the MQInput node has already propagated the message to the Catch terminal and an exception is thrown in the flow connected to the Catch terminal, the message is returned to the MQInput node:
    • The MQInput node writes the error to the local error log.
    • The message is rolled back to the input queue.
  • If the MQInput node has already propagated the message to the Failure terminal and an exception is thrown in the flow connected to the Failure terminal, the message is returned to the MQInput node and rolled back to the input queue. The MQInput node writes the error to the local error log and invokes the retry logic, described in Handling retry processing. The message is not propagated to the Catch terminal, even if that is connected.

This action is summarized in the following table.

Error event Failure terminal connected Failure terminal not connected Catch terminal connected Catch terminal not connected
Node detects internal error Flow connected to the Failure terminal handles the error Message put to alternative queue; node retries if the put fails Not applicable Not applicable
Node propagates message to out terminal, exception occurs in out flow Not applicable Not applicable Flow connected to the Catch terminal handles the error Node retries
Node propagates message to Catch terminal, exception occurs in flow connected to the Catch terminal Error logged, message rolled back Error logged, message rolled back Not applicable Not applicable
Node propagates message to Failure terminal, exception occurs in flow connected to the Failure terminal Not applicable Not applicable Node retries Node retries

Handling retry processing

The node attempts retry processing when a message is rolled back to the input queue. The node checks whether the message has been backed out before, and if it has, whether the backout count has reached (equalled) the backout threshold. The backout count for each message is maintained by WebSphere® MQ in the MQMD.

You specify (or allow to default to zero(0)) the backout threshold attribute BOTHRESH when you create the queue. If you accept the default value of 0, the node increases this value to one (1). The node also sets the value to 1 if it cannot detect the current value. If the backout threshold is set to 1, the message is processed once but it is not retried through the Out terminal of the MQInput node. To retry the message at least once, set the backout threshold to 2.

  1. If the node has propagated a message to the Out terminal many times following repeated failed attempts in the output flow, and the number of retries has reached the backout threshold limit, the node attempts to propagate the message through the Failure terminal if that is connected. If you have not connected the Failure terminal, the node attempts to put the message to another queue. When a message is propagated through the Failure terminal, the exception list does not contain the exceptions that occurred in the flows connected to the Out or Catch terminals; the exception list contains new exceptions that cover the reason that the message has gone through the Failure terminal (for example, the backout threshold was reached).

    If a failure occurs beyond the Failure terminal, further retries are made until the backout count field in the MQMD reaches twice the backout threshold set for the input queue. When this limit is reached, the node attempts to put the message to another queue.

  2. If the backout threshold has not been reached, the node gets the message from the queue again. If this fails, this is handled as an internal error (described above). If it succeeds, the node propagates the message to the out flow.
  3. If the backout threshold has been reached:
    • If you have connected the Failure terminal, the node propagates the message to that terminal. You must handle the error on the flow connected to the Failure terminal.
    • If you have not connected the Failure terminal, the node attempts to put the message on an available queue, in order of preference:
      1. The message is put on the input queue's backout requeue name (queue attribute BOQNAME), if one is defined.
      2. If the backout queue is not defined, or it cannot be identified by the node, the message is put on the dead letter queue (DLQ), if one is defined. (If the broker's queue manager has been defined by the mqsicreatebroker command, a DLQ with a default name of SYSTEM.DEAD.LETTER.QUEUE has been defined and is enabled for this queue manager.) The MQDLH PutApplName property is set to WebSphereMQIntegrator and appended with the broker major version number, for example: WebSphereMQIntegrator9
      3. If the message cannot be put on either of these queues because there is an MQPUT error (including queue does not exist), or because they cannot be identified by the node, it cannot be handled safely without risk of loss.

        The message cannot be discarded, therefore the message flow continues to attempt to backout the message. It records the error situation by writing errors to the local error log. A second indication of this error is the continual incrementing of the BackoutCount of the message in the input queue.

        If this situation has occurred because neither queue exists, you can define one of the backout queues mentioned above. If the condition preventing the message from being processed has cleared, you can temporarily increase the value of the BOTHRESH attribute. This forces the message through normal processing.

  4. If twice the backout threshold has been reached or exceeded, the node attempts to put the message on an available queue, in order of preference, as defined in the previous step.

Handling transactions, event monitoring, and backout processing

When the MQInput node performs retry processing, it can backout the transaction by putting the message to the backout requeue queue or the dead letter queue. The backout count is checked when the message is received from the input queue. If the backout threshold is exceeded, the message is backed out immediately with no further processing performed on the message. The backout operation occurs in a separate transaction from previous processing failures, and the message is not parsed or validated during the backout transaction. The backout transaction generates its own set of monitoring events. Therefore, information that is obtained through message parsing, such as the exceptionList, might not be available.

Handling message group errors

WebSphere MQ supports message groups. You can specify that a message belongs to a group and its processing is then completed with reference to the other messages in the group (that is, either all messages are committed or all messages are rolled back). When you send grouped messages to a broker, this condition is upheld if you have configured the message flow correctly, and errors do not occur during group message processing.

To configure the message flow to handle grouped messages correctly, follow the actions described in the MQInput node. However, correct processing of the message group cannot be guaranteed if an error occurs while one of the messages is being processed.

If you have configured the MQInput node as described, under normal circumstances all messages in the group are processed in a single unit of work which is committed when the last message in the group has been successfully processed. However, if an error occurs before the last message in the group is processed, the unit of work that includes the messages up to and including the message that generates the error is subject to the error handling defined by the rules documented here, which might result in the unit of work being backed out.

However, any of the remaining messages in the group might be successfully read and processed by the message flow, and therefore are handled and committed in a new unit of work. A commit is issued when the last message is encountered and processed. Therefore if an error occurs in a group, but not on the first or last message, it is possible that part of the group is backed out and another part committed.

If your message processing requirements demand that this situation is handled in a particular way, you must provide additional error handling to handle errors in message groups. For example, you could record the failure of the message group in a database, and include a check on the database when you retrieve each message, forcing a rollback if the current group has already encountered an error. This would ensure that the whole group of messages is backed out and not processed unless all are successful.

Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2016Copyright IBM Corporation 1999, 2016.

        
        Last updated:
        
        Last updated: 2016-05-23 14:46:00


Task topicTask topic | Version 8.0.0.7 | ac00414_