BLOCK-LEVEL ON ERROR UNDO, THROW statement

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 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.

References:

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.

See also 

ON ENDKEY phrase, ON ERROR phrase, ON QUIT phrase, RETURN statement, RETURN-VALUE function, ROUTINE-LEVEL ON ERROR UNDO, THROW statement, STOP statement, UNDO-THROW-SCOPE attribute