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.

CREATE PROCEDURE getLastExceptionDetail(IN InputTree reference,OUT messageNumber integer,
OUT messageText char)	
    /****************************************************************************
	 * A procedure that will get the details of the last exception from a message
	 * IN InputTree:  The incoming exception list
	 * IN messageNumber:  The last message numberr.
	 * IN messageText: The last message text.
	 *****************************************************************************/
   BEGIN
   	    -- Create a reference to the first child of the exception list
   	    declare ptrException reference to InputTree.*[1];
   	    -- keep looping while the moves to the child of exception list work 
		WHILE lastmove(ptrException) DO
			-- store the current values for the error number and text
			IF ptrException.Number is not null THEN
        		SET messageNumber = ptrException.Number;
        		SET messageText = ptrException.Text;
  			END IF;
  			-- now move to the last child which should be the next exceptionlist
			move ptrException lastchild;
		END WHILE; 
	END;

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 overview
ExceptionList tree structure
ESQL overview
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 reference
DECLARE statement
EVAL statement
WHILE statement