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

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