Exception list tree structure

The exception list tree is a part of the logical message tree in which the message flow writes information about exceptions that occur when a message is processed.

The root of the exception list tree is called ExceptionList, and the tree consists of a set of zero or more exception descriptions. The exception list tree is populated by the message flow if an exception occurs. If no exception conditions occur during message flow processing, the exception list that is associated with that message consists of a root element only. This list is, in effect, an empty list of exceptions.

The exception list tree can be accessed by other nodes in the message flow that receive the message after the exception has occurred. You can modify the contents of the exception list tree only in a node that provides an interface to modify the outbound message tree; for example, the Compute node.

If an exception condition occurs, message processing is suspended and an exception is thrown. Control is passed back to a higher level; that is, an enclosing catch block. An exception list is built to describe the failure condition, and the whole message, together with the local environment tree, and the newly-populated exception list, is propagated through an exception-handling message flow path.

The child of ExceptionList may be any one of the exception types that is included in the following list. Typically, only one child of the root is created, although more than one might be generated in some circumstances. The child of ExceptionList contains a number of children, each of which may also be any one of the types in the following list. The last of these children provides further information specific to the type of exception.
  • FatalException
  • RecoverableException
  • ConfigurationException
  • SecurityException
  • ParserException
  • ConversionException
  • DatabaseException
  • UserException
  • CastException
  • MessageException
  • SqlException
  • SocketException
  • SocketTimeoutException
  • UnknownException

The following figure shows the structure of the exception list tree for a recoverable exception:

Exception list tree structure for a recoverable exception

The exception description structure can be both repeated and nested to produce an exception list tree. In this tree:

  • The depth (that is, the number of parent-child steps from the root) represents increasingly detailed information for the same exception.
  • The width of the tree represents the number of separate exception conditions that occurred before processing was abandoned. This number is usually one, and results in an exception list tree that consists of a number of exception descriptions that are connected as children of each other.
  • At the numbered points in the tree:
    1. This child can be any one of the exception types that are listed earlier in this topic. All of these elements have the children shown; if present, the last child is the same element as its parent.
    2. This element might be repeated.
    3. If present, this child contains the same children as its parent.

The children in the tree take the form of a number of name-value elements that give details of the exception, and zero or more name elements whose name is Insert. The NLS (National Language Support) message number identified in a name-value element identifies an IBM® Integration Bus error message. The Insert values are used to replace the variables in this message and provide further detail about the cause of the exception.

The name-value elements in the exception list shown in the figure above are described in the following table.

Name Type Description
File1 String C++ source file name
Line1 Integer C++ source file line number
Function1 String C++ source function name
Type2 String Source object type
Name2 String Source object name
Label2 String Source object label
Text1 String Optional non-NLS text
Catalog3 String NLS message catalog name4
Severity3 Integer
1 = information
2 = warning
3 = error
Number3 Integer NLS message number4
Insert3 Type Integer The data type of the value:
0 = Unknown
1 = Boolean
2 = Integer
3 = Float
4 = Decimal
5 = Character
6 = Time
7 = GMT Time
8 = Date
9 = Timestamp
10 = GMT Timestamp
11 = Interval
12 = BLOB
13 = Bit Array
14 = Pointer
Text String The data value
Notes:
  1. Do not use the File, Line, Function, and Text elements for exception handling decision making. These elements ensure that information can be written to a log for use by IBM Service personnel, and are subject to change in both content and order.
  2. The Type, Name, and Label elements define the object (usually a message flow node) that was processing the message when the exception condition occurred.
  3. The Catalog, Severity, and Number elements define an NLS message: the Insert elements that contain the two name-value elements shown define the inserts into that NLS message.
  4. NLS message catalog name and NLS message number refer to a translatable message catalog and message number.

When the message flow processing is complete, the exception list tree is discarded.