ON
Declares a block of commands to be a handler for a given exception condition.
Syntax
ON condition
commands
ENDON
Parameters
| condition
|
One of BREAK Handles a terminal or process break condition (i.e., the user pressing the “break” key). DEADLOCK Handles a deadlock condition (i.e., $ErrCode=2010). ERROR Handles an error condition. WARNING Handles a warning condition.
|
| commands
|
Commands to be executed should the associated exception condition arise. Cannot include a nested ON … ENDON, a GOTO command, or a SET EXCEPTION command.
|
Comments
The ON … ENDON structure enables you to detect and handle exception conditions that can arise in your application. The exception handler is executed only if the associated exception condition arises.
Note: An application program can explicitly trigger an exception handler using the SET EXCEPTION command.
Exception handlers are declared and recognized only within a procedure. All exception handlers must be declared at the start of the procedure, immediately following the PROCEDURE or LOCALPROCEDURE command.
An exception handler cannot be nested inside another exception handler. As a result, exception conditions that arise during the execution of an exception handler do not trigger a subsequent exception handler.
You cannot nest exception handlers; that is, you cannot declare an exception handler within another exception handler without another exception handler declaration.
When execution control shifts to a procedure, exception handler declarations are noted, but the body of each exception handler is ignored for the moment. Execution begins at the first command following the last exception handler declaration. When an exception condition arises and a corresponding exception handler exists, the exception handler is triggered: execution of the commands in the procedure are suspended, and execution control is transferred to the body of the exception handler.
Note: All programming structures (CASE, IF, WHILE) that are opened within an exception handler must be closed within that handler.
RECURSIVE EXCEPTION CONDITIONS
An exception handler cannot be triggered from within an exception handler. In other words, exception conditions that arise during execution of the body of an exception handler are ignored. For example, a DEADLOCK condition raised during the execution of an ERROR exception handler does not trigger the DEADLOCK exception.
Similarly, the SET EXCEPTION command cannot be used in the body of an exception handler.
EXCEPTION HANDLER HIERARCHY
Under certain circumstances, a number of exception conditions can arise at the same time.
For example, if the application user presses the break key while an error message is being issued, the BREAK and ERROR conditions both are raised. Deadlock in multi-user applications always results in multiple exception conditions, because the deadlock produces a warning message (i.e., resulting in both a DEADLOCK and an WARNING condition being raised).
Simultaneous exception conditions are handled in the following order:
If multiple exception conditions arise, the software looks for an exception handler for the condition with the highest precedence. If there is no handler for that condition, the software then looks for an exception handler for the condition with the next-highest precedence, and so on.
Only the exception handler that is uppermost in the hierarchy is triggered.
HANDLING TERMINAL BREAKS
An application user can prematurely stop execution of a procedure by pressing the “break” key, causing a terminal break.
When a terminal break occurs, the software normally terminates the command that is currently executing and performs a RETURN (i.e., returns to the parent procedure). However, if a BREAK exception handler is available when a terminal break occurs, the software stops the command that is currently executing and triggers the BREAK handler instead. The BREAK handler can then deal with break signals in a customized manner.
To prevent terminal breaks from raising a BREAK condition, use the SET BREAKABLE command.
Example
Exception handlers must appear first within a procedure:
procedure MyProc (Param1, Param2)
on break
… commands that handle the “break” condition …
endon
… procedure commands …
endprocedure
You can declare more than one exception handler in a procedure:
procedure MyProc (Param1,Param2)
on deadlock
… commands that handle the “deadlock” condition …
endon
on error
… commands that handle the “error” condition …
endon
… procedure commands …
endprocedure
Execution flow in the procedure varies depending on the conditions that are encountered in the body of the procedure (following the last ENDON).