Try OpenEdge Now
skip to main content
Error Handling
Traditional Error Handling : Specifying error handling behavior
 

Specifying error handling behavior

The ON ERROR phrase is the ABL tool for altering the default error handling for basic blocks. This is the syntax for the ON ERROR phrase:

Syntax

ON ERROR UNDO
[label1]
[ , LEAVE [label2]
| , NEXT [label2]
| , RETRY [label1]
     | , RETURN [return-value |
                  ERROR [return-value |error-object-expression]|
                  NO-APPLY ]
     | , THROW
]
The syntax options are nearly identical to those of the UNDO statement shown in ABL BlockEssentials.
label1
The name of the block whose processing you want to undo. If you do not name a block with label1, ON ERROR UNDO undoes the processing of the block started by the statement that contains the ON ERROR phrase.
LEAVE [label2]
Indicates that after undoing the processing of a block, the AVM leaves the block labeled label2. If you do not name a block, the AVM leaves the block labeled with label1.
NEXT [label2]
Indicates that after undoing the processing of a block, the AVM executes the next iteration of the block you name with the label2 option. If you do not name a block with the NEXT option, the AVM executes the next iteration of the block labeled with label1.
RETRY [label1]
Indicates that after undoing the processing of a block, the AVM repeats the same iteration of the block you name with the label1 option.
RETRY is the default branching option if you do not use an explicit LEAVE, NEXT, RETRY, or RETURN option. Because RETRY in a block without user input results in an infinite loop, the AVM automatically checks for this possibility and converts a RETRY block into a LEAVE block or a NEXT block if it is an iterating block. This behavior is often referred to as infinite loop protection.
RETURN ...
Indicates that after undoing the processing of a block, the AVM executes the next iteration of the block you name with the label2 option. If you do not name a block with the NEXT option, the AVM executes the next iteration of the block labeled with label1.
Returns to the calling routine, or if there is no calling routine, returns to the OpenEdge Editor. The following table describes various RETURN cases:
Table 3. RETURN cases
Option
Description
return-value
The CHARACTER string you provide is passed to the caller. The caller can use the RETURN-VALUE function to read the returned value. For user-defined functions, the value must match the specified return type.
ERROR
Raises ERROR in the caller and undoes the current subtransaction. You cannot specify ERROR within a user-interface trigger block or a destructor.
ERRORreturn-value
Raises ERROR in the caller and undoes the current subtransaction (except for user-defined functions). The CHARACTER string you provide is available to the caller in the RETURN-VALUE function. In structured error handling, the AVM also creates an AppError object and stores the return-value in the ReturnValue property.
ERRORerror-object-expression
In structured error handling, raises ERROR in the caller and undoes the current subtransaction.The specified error object is your code. If it is an AppError object, the caller can also use the RETURN-VALUE function to read the setting of the ReturnValue property.
NO-APPLY
In a user-interface trigger, prevents the AVM from performing the default behavior for that event.
THROW (structured error handling only)
Use this directive to explicitly propagate an error to the enclosing block. This option is explained in detail in Raisingerrors with THROW
The options of the ON ERROR phrase are parallel to the block properties that define default error handling for a block. All blocks, except the simple DO block, have an implicit ON ERROR phrase. So, for a procedure block, which does not support an explicit ON ERROR phrase, you can say that the procedure block has an implicit ON ERROR phrase. It is an implicit ON ERROR UNDO, LEAVE phrase if the procedure block does not contain user input. If the procedure block does contain user input, then it has an implicit ON ERROR UNDO, RETRY phrase.
Going forward, this manual uses the notion of an implicit (or explicit) ON ERROR phrase to describe the error handling properties of blocks. This terminology change makes it easy to compare different blocks and different use cases.
* Using labels