Accessing the ExceptionList tree

The ExceptionList tree has its own correlation name, ExceptionList, and you must use this in all ESQL statements that refer to or set the content of this tree.

This tree is created with the logical tree when an input message is parsed. It is initially empty, and is only populated if an exception occurs during message flow processing. It is possible that more than one exception can occur; if this happens, the ExceptionList tree contains a subtree for each exception.

You can access the ExceptionList tree in Compute, Database, and Filter nodes, and you can update it in a Compute node. You must use the appropriate correlation name; Exception List for a Database or Filter node, and InputExceptionList for a Compute node.

You might want to access this tree in a node in an error handling procedure. For example, you might want to route the message to a different path based on the type of exception, for example one that you have explicitly generated using an ESQL THROW statement, or one that the broker has generated.

The following ESQL shows how you can access the ExceptionList and process each child that it contains:

-- Declare a reference for the ExceptionList
-- (in a Compute node use InputExceptionList)
DECLARE start REFERENCE TO ExceptionList.*[1];

-- Loop through the exception list children
WHILE start.Number IS NOT NULL DO 
   -- more ESQL

   -- Move start to the last child of the field to which it currently points 
   MOVE start LASTCHILD;
END WHILE;         

The second example below shows an extract of ESQL that has been coded for a Compute node to loop through the exception list to the last (nested) exception description and extract the error number. This error relates to the original cause of the problem and normally provides the most precise information. Subsequent action taken by the message flow can be decided by the error number retrieved in this way.

-- Declare variable for the Error number extracted from exception list
DECLARE Error INTEGER;
-- Declare current path within the exception list
DECLARE Path CHARACTER;

-- Start at first child of exception list
SET Path = 'InputExceptionList.*[1]';

-- Loop until no more children 
WHILE EVAL( 'FIELDNAME(' || Path || ') IS NOT NULL' ) DO

  -- Check if error number is available 
  IF EVAL( 'FIELDNAME(' || Path || '.Number) IS NOT NULL' ) THEN
    -- Record only the deepest error number 
    SET Error = EVAL( Path || '.Number' );
  END IF;

 -- Step to last child of current element (usually a nested exception list
 SET Path = Path || '.*[<]';

END WHILE; 

For more information about the use of ExceptionList, refer to the subflow in the Error Handler sample, which includes ESQL that interrogates the ExceptionList structure and takes specific action according to its content.

Related concepts
Message flows
ExceptionList tree
ESQL
Message modeling

Related tasks
Handling errors in message flows
Designing a message flow
Defining message flow content
Managing ESQL files

Related reference
Compute node
Exception list structure
ESQL
DECLARE statement
EVAL statement
WHILE statement