FINALLY statement

Defines a final end block for any ABL block. An end block is an ABL block that can occur only within another block. The block containing the end block is known as the associated block. End-blocks must occur between the last line of executable code in the associated block and the END statement.

For any ABL block statement, the FINALLY statement defines an optional end block that contains ABL code to execute at the conclusion of all other processing in the associated block or once at the conclusion of each iteration of an associated iterating block. This is the syntax for the FINALLY statement and its related blocks:

`block-statements` FINALLY : `finally-logic` END [ FINALLY ] . [ `block-end-statement` ]

All of the statements of an enclosing associated ABL block, except for its block-end-statement. The enclosing associated block can be any ABL block, including another FINALLY block

All statements allowed in a FINALLY block, which can include any valid ABL statement. For more information on FINALLY block execution, see the notes for this reference entry.

For all associated ABL blocks except a main external procedure block, the END statement terminating the enclosing associated block of the FINALLY block. External procedure blocks have no terminating END statement.

As shown in r-finally01.p, the FINALLY block executes before any flow-of-control (LEAVE, NEXT, RETRY, RETURN, or THROW) options are executed for the associated block. For iterating blocks, the FINALLY block executes after each iteration of the block.

r-finally01.p
DO ON ERROR UNDO, LEAVE: /* Since Customer 1000 does not exist, the FIND statement raises ERROR and execution goes to FINALLY block before the LEAVE option executes. / FIND Customer 1000. MESSAGE "This message never appears because of ERROR condition." VIEW-AS ALERT-BOX BUTTONS OK. FINALLY: MESSAGE "Inside FINALLY block." VIEW-AS ALERT-BOX BUTTONS OK. / LEAVE DO block here / END FINALLY. END. / DO */ MESSAGE "Out of DO block." VIEW-AS ALERT-BOX BUTTONS OK.

In r-finally02.p, after ERROR is raised, execution goes to the CATCH block and then to the FINALLY block.

r-finally02.p
DO ON ERROR UNDO, LEAVE: /* Since Customer 1000 does not exist, the FIND statement raises ERROR and execution goes to CATCH block. / FIND Customer 1000. MESSAGE "This message never appears because of ERROR condition." VIEW-AS ALERT-BOX BUTTONS OK. CATCH eSysError AS Progress.Lang.SysError: / Handler code for SysError condition / MESSAGE "Inside CATCH block." VIEW-AS ALERT-BOX BUTTONS OK. / Execution goes to FINALLY before leaving DO block. / END CATCH. FINALLY: / Your code / MESSAGE "Inside FINALLY block." VIEW-AS ALERT-BOX BUTTONS OK. / LEAVE DO block here. / END FINALLY. END. / DO */ MESSAGE "Out of DO block." VIEW-AS ALERT-BOX BUTTONS OK.

r-finally02.p

DO ON ERROR UNDO, LEAVE: 
  /* Since Customer 1000 does not exist, the FIND statement raises ERROR and 
     execution goes to CATCH block. */ 
  FIND Customer 1000. 
  MESSAGE "This message never appears because of ERROR condition."  
    VIEW-AS ALERT-BOX BUTTONS OK. 
  CATCH eSysError AS Progress.Lang.SysError: 
    /* Handler code for SysError condition */ 
    MESSAGE "Inside CATCH block." VIEW-AS ALERT-BOX BUTTONS OK. 
    /* Execution goes to FINALLY before leaving DO block. */ 
  END CATCH. 
  FINALLY: 
    /* Your code */ 
    MESSAGE "Inside FINALLY block." VIEW-AS ALERT-BOX BUTTONS OK. 
    /* LEAVE DO block here. */ 
  END FINALLY. 
END. /* DO */ 
MESSAGE "Out of DO block." VIEW-AS ALERT-BOX BUTTONS OK.

In r-finally03.p, after ERROR is raised, execution goes to the CATCH block, which re-throws the error. However, the FINALLY block executes before the error goes to the CATCH block associated with the procedure block.

r-finally03.p
DO ON ERROR UNDO, LEAVE: /* Since Customer 1000 does not exist, the FIND statement raises ERROR and execution goes to CATCH block. / FIND Customer 1000. MESSAGE "This message never appears because of ERROR condition." VIEW-AS ALERT-BOX BUTTONS OK. CATCH eSysError AS Progress.Lang.SysError: / Handler code for SysError condition / MESSAGE "Inside CATCH block." VIEW-AS ALERT-BOX BUTTONS OK. / Execution goes to FINALLY before leaving DO block. / UNDO, THROW eSysError. END CATCH. FINALLY: / Your code / MESSAGE "Inside FINALLY block." VIEW-AS ALERT-BOX BUTTONS OK. END FINALLY. END. / DO */ CATCH eSysError AS Progress.Lang.SysError: MESSAGE "Out of DO block and inside CATCH block for procedure block" VIEW-AS ALERT-BOX BUTTONS OK. END CATCH.

r-finally03.p

DO ON ERROR UNDO, LEAVE: 
  /* Since Customer 1000 does not exist, the FIND statement raises ERROR and 
     execution goes to CATCH block. */ 
  FIND Customer 1000. 
  MESSAGE "This message never appears because of ERROR condition."  
    VIEW-AS ALERT-BOX BUTTONS OK. 
  CATCH eSysError AS Progress.Lang.SysError: 
    /* Handler code for SysError condition */ 
    MESSAGE "Inside CATCH block." VIEW-AS ALERT-BOX BUTTONS OK. 
    /* Execution goes to FINALLY before leaving DO block. */ 
    UNDO, THROW eSysError. 
  END CATCH. 
  FINALLY: 
    /* Your code */ 
    MESSAGE "Inside FINALLY block." VIEW-AS ALERT-BOX BUTTONS OK. 
  END FINALLY. 
END. /* DO */ 
CATCH eSysError AS Progress.Lang.SysError: 
  MESSAGE "Out of DO block and inside CATCH block for procedure block"  
    VIEW-AS ALERT-BOX BUTTONS OK. 
END CATCH.

There can be only one FINALLY block in any associated block. The FINALLY statement must come after all other executable statements in the associated block. If the associated block contains CATCH statements, the FINALLY block must come after all CATCH blocks. Note that the FINALLY statement can be used in a block with no CATCH blocks.

The FINALLY block executes as an end block of the associated block. This means that the FINALLY block cannot execute until the associated block executes. The FINALLY block executes once for each iteration of its associated block. This means you can only execute the FINALLY block during the execution of the associated block. The FINALLY block executes on success or failure of the associated block.

Thus, the FINALLY block executes:

After successful execution of the associated block

After each successful iteration of an iterating associated block

After ERROR is raised in the associated block and a CATCH block handles the error

After ERROR is raised in the associated block and no CATCH handles the error

The FINALLY block will not execute:

If a STOP condition is raised

If a QUIT statement is in effect

The purpose of a FINALLY block is to hold clean-up code that must execute regardless of what else executed in the associated block. It can include code to delete objects and dynamic objects, write to logs, close outputs, and other routine tasks. Because it executes even if the ERROR condition is raised, the FINALLY block is also a useful part of a structured error handling scheme.

Since it executes after an invoked CATCH block, the FINALLY block can also be used to perform common post-CATCH clean up tasks, rather than repeating common code in all the CATCH blocks present in the associated block.

The transaction of the associated block is either complete (success) or undone (failure) when FINALLY executes. Therefore, any UNDO statement within the FINALLY block will only undo the work in the FINALLY block.

The FINALLY block is an undoable block with implicit ON ERROR UNDO, THROW error handling. You cannot explicitly override the ON ERROR directive for a FINALLY block. If a statement within the FINALLY block raises ERROR, the FINALLY block will be undone, and ERROR will be raised in the block that encloses the associated block of the FINALLY block. Error is not raised in the associated block. Otherwise, infinite looping could occur.

A statement that raises ERROR within a FINALLY end block causes the following to occur:

UNDO the FINALLY block.

LEAVE the associated block.

THROW the error to the block enclosing the associated block.

The same behavior occurs for an explicit THROW statement in a FINALLY block.

The code in any FINALLY block can contain explicit flow-of-control options: LEAVE, NEXT, RETRY, RETURN, or THROW. Since FINALLY is an undoable block, LEAVE, NEXT, and RETRY without a label apply to the FINALLY block itself and not to the associated block.

If you want LEAVE, NEXT, or RETRY to apply to the associated block, use label syntax with these statements. Flow of control statements in a FINALLY block override pending flow of control from a CATCH block.

If the AVM detects a STOP or QUIT condition in the associated block, the FINALLY block will not run and the AVM processes the condition. If the associated block has an ON STOP or ON QUIT phrase, then the STOP or QUIT condition is handled and released by the time the AVM is ready to execute the FINALLY block, and the FINALLY block is executed. See the ON STOP and ON QUIT reference entries for a description of the STOP and the QUIT condition behavior and handling.