ON STOP phrase

Describes processing that occurs when the STOP condition is raised. The STOP condition is raised when:

• The user presses the STOP key (usually mapped to CTRL+BREAK in Windows and CTRL+C on Unix/Linux.)
• The time-out is exceeded for a STOP-AFTER directive on a DO, FOR, or REPEAT statement.
• The time-out set using the Lock Timeout (-lkwtmo) startup parameter is exceeded when waiting for release of a record lock, or when the user indicates they want to stop waiting.
• A STOP statement executes.
• System errors occur that raise the STOP (instead of the ERROR) condition.

By default, when a STOP condition occurs in a block, all the changes to persistent data (database fields) are undone. If the block is a transaction block, undo variables and temp-table fields are also undone. See OpenEdge Getting Started: ABL Essentials for more information on transaction blocks. The ON STOP phrase can be used to modify the scope of UNDO processing, possibly widening it to an outer block.

Also by default, a STOP condition causes execution to leave the current block. The STOP condition is continually propagated to the outer block, or up the call stack if there is no outer block. The ON STOP phrase can be used to control where execution continues and to clear the STOP condition so that it is not propagated beyond the current block.

The AVM performs stop handling using this precedence, from highest to lowest. The AVM only abides by one of these when a STOP is raised:

• CATCH block
• Block’s ON phrase (explicit or implicit)

Due to this precedence, the ON STOP phrase is ignored if a local CATCH block handles the stop.

Syntax

ON STOP UNDO
  [label1]
  [     , LEAVE [ label2 ]
     |  , NEXT [ label2 ]
     |  , RETRY [ label1 ]
     |  , RETURN [ return-value |
                  ERROR [ return-value | error-object-expression ] |
                  NO-APPLY ]
  ]

label1

The name of the block whose processing you want to undo. If you do not name a block with label1, the AVM undoes the processing of the current block.

LEAVE [label2]

Indicates that, after undoing the processing of a block, the AVM leaves the block labeled label2. If you do not name a block, the AVM leaves the current block. There are restrictions. For example, you cannot undo an outer block, but leave only the inner block.

NEXT [label2]

Indicates that, after undoing the processing of a block, the AVM executes the next iteration of the block you name with the label2 option. If you do not name a block with the NEXT option, the AVM executes the next iteration of the current block.

RETRY [label1]

Indicates that after undoing the processing of a block, the AVM repeats the same iteration of the block.

Because RETRY in a block without user input results in an infinite loop, the AVM automatically checks for this possibility and converts a RETRY block into a LEAVE block, or a NEXT block if it is an iterating block. This behavior is often referred to as infinite loop protection.

RETURN ...

Returns to the calling routine, if there is one. The following table describes various RETURN options:

Option	Description
return-value	In procedures and VOID methods, this must be a CHARACTER string. The caller can use the RETURN-VALUE function to read the returned value. For user-defined functions, non-VOID methods and property getters, the value must match the specified return type.
ERROR	Undoes the current subtransaction, and raises ERROR in the caller. You cannot specify ERROR within a user-interface trigger block or a destructor. For user-defined functions see note below.
ERROR return-value	Undoes the current subtransaction, and raises ERROR in the caller. The CHARACTER string you provide is available to the caller in the RETURN-VALUE function. The AVM also creates an AppError object and stores the return-value in the ReturnValue property. For user-defined functions see note below.
ERROR error-object-expression	Undoes the current subtransaction, and raises ERROR in the caller. The specified error object instance is thrown to the caller. For user-defined functions see note below.
NO-APPLY	In a user-interface trigger, prevents the AVM from performing the default behavior for the trigger event. Otherwise, the option is ignored.

Note: Using RETURN ERROR in a user-defined function sets the target variable of the function to the Unknown value (?) instead of raising ERROR in the caller. See OpenEdge Development: ABL Error Handling for more detail.

Example

This procedure lets you update the CreditLimit field for each Customer. If you enter a value greater than 100,000, the program raises the STOP condition. Since you specified an UNDO, RETRY for a STOP, the procedure starts the iteration over and allows you to enter another value.

r-ostop.p

FOR EACH Customer ON STOP UNDO, RETRY:
  DISPLAY Customer.CustNum Customer.Name Customer.CreditLimit.
  UPDATE Customer.CreditLimit.
  IF Customer.CreditLimit > 100000 THEN STOP.
END.

Notes

• When both a local ON STOP phrase and a matching local CATCH block is specified on the current block, the local CATCH block takes precedence and the ON STOP phrase is ignored. If no local CATCH block matches the thrown stop object type, the specified directive in the local ON STOP phrase executes instead for any raised STOP condition.
• Almost all STOP conditions are trappable with the ON STOP phrase or a CATCH block. In some cases, the AVM might ignore STOP conditions at certain levels of the call stack. For example, if the AVM executes a procedure that relies on a database and the connection is lost, the AVM raises the STOP condition and unwinds the call stack until it gets to a level above all references to the database. ON STOP phrases and compatible CATCH blocks before this point are ignored. After this point, the AVM executes the directive specified in the ON STOP phrase or compatible CATCH block, with the CATCH block taking precedence if the ON STOP phrase is on the same associated block.
• If a block does not have implicit error handling capabilities (for example, a simple DO or DO WHILE block) you can add the ON STOP (or ON ERROR) phrase to explicitly turn it into one with error handling. This allows you to use a CATCH statement within the block to catch any error or stop conditions. If you don't add the ON STOP (or ON ERROR) phrase and try to use a CATCH within the block, you get a compiler error.

See also

CATCH statement, ON ENDKEY phrase, ON ERROR phrase, ON QUIT phrase, Progress.Lang.Stop class, Progress.Lang.StopError class, RETURN statement, RETURN-VALUE function, STOP statement