ROUTINE-LEVEL ON ERROR UNDO, THROW statement

Use this statement in a procedure (.p) or class (.cls) file to change the default ON ERROR phrase associated with routine-level blocks and ON blocks used as database triggers.

Syntax

ROUTINE-LEVEL ON ERROR UNDO, THROW.

The undoable blocks (DO, FOR, and REPEAT), support the ON ERROR UNDO, THROW phrase. This phrase is useful for propagating errors up the call stack where they can be handled by CATCH blocks associated with higher level blocks. This technique eliminates the need for CATCH blocks handling common error types at every level in a series of nested blocks.

The main blocks of ABL routines do not support explicit ON ERROR phrases. The following blocks are called routine-level blocks:

Main block of an external procedure (.p)
Internal procedure
User-defined function
Method of a class
Class constructor
Property accessor

The routine-level blocks have an implicit, default ON ERROR UNDO, RETRY phrase (with infinite loop protection). Therefore, you cannot change the default behavior for routine-level blocks to throw or re-throw errors with the ON ERROR phrase.

The ROUTINE-LEVEL ON ERROR UNDO, THROW statement for class (.cls) and procedure (.p) files changes the default implicit ON ERROR phrase to ON ERROR UNDO, THROW for every routine-level block contained in the file.

Similarly, when an ON block is a database trigger with a CREATE, DELETE, WRITE or ASSIGN event, the ROUTINE-LEVEL ON ERROR UNDO, THROW statement changes the implicit ON ERROR phrase to ON ERROR UNDO, THROW.

The following are rules affecting the placement of this statement:

This statement must come before any definitional or executable statement in the procedure or class file.
The statement can come before or after a USING statement.

Example

This block propagates an error from a DO block up to the main procedure block. A CATCH block on the main procedure block handles the error.

r-ROUTINE-LEVEL-01.p

ROUTINE-LEVEL ON ERROR UNDO, THROW. PROCEDURE find1000:   FIND FIRST Customer WHERE Customer.CustNum = 1000. END PROCEDURE. PROCEDURE find2000:   FIND FIRST Customer WHERE Customer.CustNum = 2000. END PROCEDURE. PROCEDURE find3000:   FIND FIRST Customer WHERE Customer.CustNum = 3000. END PROCEDURE. /* Main Block */ RUN find1000. RUN find2000. RUN find3000. CATCH eAnyError AS Progress.Lang.SysError:   MESSAGE "Your CATCH block associated with the the main block (.p) has handled an error in an internal procedure."     VIEW-AS ALERT-BOX BUTTONS OK. END CATCH.

Notes

The term routine level should not be mistaken to imply that you can define a single CATCH block at the class or procedure file level that will handle an error type from any sub-procedure in a persistent procedure or method in a class. The statement simply alters default error handling behavior of all sub-procedures and methods within the file. For these “routine-level” blocks, the default error handing behavior is changed from ON ERROR UNDO, RETRY to ON ERROR UNDO, THROW. The ROUTINE-LEVEL ON ERROR UNDO, THROW statement behavior guarantees that all unhandled errors in a sub-procedure of a persistent procedure or method of a class will be propagated up to the caller. You decide for each sub-procedure or method within the file whether that sub-procedure or method should handle errors locally with its own CATCH blocks. Alternatively, you may want to avoid local CATCH blocks and let the caller handle all errors with a CATCH block at the caller level. This can be useful if a caller calls many internal procedures in a persistent procedure or many methods in a class.
This statement does not apply to destructors, since destructors cannot raise error in the caller. The statement has no effect on DO, FOR, or REPEAT blocks contained within the routine-level blocks. The statement has no effect on ON blocks that are UI triggers.
When a routine-level block or a database trigger has a CATCH statement that explicitly handles the thrown error, then the CATCH block handles the error and it is not thrown up the call stack (unless the CATCH block rethrows it).

See also

ON ENDKEY phrase, ON ERROR phrase, ON QUIT phrase, RETURN statement, RETURN-VALUE function, STOP statement

OpenEdge Release 10.2B

Copyright © 2009 Progress Software Corporation