Use this statement in a procedure (.p) or class (.cls) file to change the default ON ERROR
directive to UNDO, THROW for all blocks that have a default error directive associated with
them. (A simple DO block, for example, does not have default error handling and is not
affected by this statement.). The default ON ERROR directive is either
UNDO, LEAVE or UNDO, RETRY, depending on the block type.
The statement must come before
any executable or DEFINE statements in a file. However, it can come
either before or after a USING statement.
Syntax
BLOCK-LEVEL ON ERROR UNDO, THROW.
|
This statement affects the following block types:
- Main block of an external procedure (.p)
- Internal procedures
- User-defined functions
- Methods of a class
- Class constructors
- Property accessors
- ON blocks used as database triggers with CREATE, DELETE, WRITE or
ASSIGN events
- REPEAT blocks
- FOR blocks
- DO TRANSACTION blocks
This statement does not affect:
- Destructors
- Error directives that are explicitly coded in individual, non routine-level
blocks
- ON blocks that are UI triggers.
Note these alternatives
to the BLOCK-LEVEL ON ERROR UNDO, THROW statement:
- Instead
of adding the statement to source-code files, you can use the -undothrow 2 startup
parameter to change the default error-handling to UNDO, THROW on
every block affected by the BLOCK-LEVEL statement during compilation.
See the OpenEdge Deployment: Startup Command and Parameter
Reference for more information.
- The ROUTINE-LEVEL ON ERROR UNDO, THROW statement can be used if you want to change
the default error-handling only on routine-level blocks. (You can
use the -undothrow 1 startup parameter
to change the default error-handling on routine-level blocks to
UNDO, THROW during compilation.)
Example
An
error propagates from the DO TRANSACTION block to the internal procedure,
from the internal procedure up to the main .p file (b-BLOCK-LEVEL-01.p),
and finally up to the CATCH block in the calling .p file (b-BLOCK-LEVEL-02.p).
An error is raised at each of these levels. At each level the ON
ERROR UNDO, THROW directive takes effect.
b-BLOCK-LEVEL-01.p
BLOCK-LEVEL ON ERROR UNDO, THROW.
/* Update first order for a customer shipped by a certain date */
DEFINE INPUT PARAMETER custName AS CHAR.
DEFINE INPUT PARAMETER latestShipDate AS DATE.
RUN updateCustomers.
PROCEDURE updateCustomers:
DO TRANSACTION:
FIND customer WHERE customer.NAME = custName.
FIND order OF customer WHERE shipDate < latestShipDate.
UPDATE order.
END.
END.
|
b-BLOCK-LEVEL-02.p
RUN b-BLOCK-LEVEL-01.p (INPUT cValue, INPUT dDate).
CATCH err AS Progress.Lang.Error:
MESSAGE "Customer or order not found " err:GetMessage(1)
VIEW-AS ALERT-BOX INFO BUTTONS OK.
END.
|
Notes
- The
BLOCK-LEVEL ON ERROR UNDO, THROW statement guarantees that all unhandled
errors in affected blocks will be propagated up to the caller. You
can decide whether to handle errors at the block level with a CATCH
statement, or to handle all errors with a CATCH block at a higher
level.
- The BLOCK-LEVEL statement affects the same blocks as the ROUTINE-LEVEL ON ERROR UNDO, THROW statement, plus REPEAT, FOR, and DO TRANSACTION
blocks. Therefore, there is no need to add both statements to a
file. If both statements exist in a file, the more inclusive BLOCK-LEVEL
statement takes precedence.
- When a block affected by the BLOCK-LEVEL statement has a CATCH
statement associated with it that explicitly handles the thrown error,
the CATCH block handles the error. The error is not thrown up the call
stack, unless the CATCH block rethrows it.
- Error objects can be thrown from an AppServer and handled by
a CATCH block on an ABL client. To be throwable from an AppServer
to an ABL client, user-defined error classes must be defined on
both the server and client sides, and the classes must be defined
as SERIALIZABLE. For the full list of restrictions on class-based
objects that are passed between AppServer and client, see the Parameter passing syntax entry. For more information on error handling in general,
see OpenEdge Development: Error Handling.