ON ENDKEY phrase

Defines the processing that occurs when the ENDKEY condition arises during a block. This condition usually occurs when the user presses END-ERROR during the first interaction of a block iteration, or any time the user presses a defined END-KEY.

If you use a REPEAT or FOR EACH block, the default processing for ENDKEY is to undo all the processing in the current iteration of the block, then leave the block and continue on to any remaining statements in the routine.

Syntax

ON ENDKEY 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

In this procedure, if the user presses END-ERROR or END-KEY while changing the CreditLimit field, any changes made during the current iteration of the block are undone, and the same iteration is run again. If this procedure did not use the ON ENDKEY phrase and the user pressed END-ERROR, the procedure ends because the default ENDKEY action is UNDO, LEAVE. After leaving the FOR EACH block, the procedure ends because there are no more statements.

r-endky.p

ON WINDOW-CLOSE OF CURRENT-WINDOW
  STOP.

FOR EACH Customer ON ENDKEY UNDO, RETRY:
  DISPLAY Customer.CustNum Customer.Name Customer.CreditLimit.
  SET Customer.CreditLimit 
    VALIDATE(Customer.CreditLimit > 0,"non-zero credit limit").
END.

See also

ON ERROR phrase, ON QUIT phrase, ON STOP phrase, RETURN statement, RETURN-VALUE function, UNDO statement