ON ENDKEY phrase

Describes the processing that occurs when the ENDKEY condition occurs 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.

Note: Does not apply to SpeedScript programming.

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, ON ENDKEY UNDO undoes the processing of the block started by the statement that contains the ON ENDKEY phrase.

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 block containing the ON ENDKEY phrase. After leaving a block, the AVM continues on with any remaining processing in a routine. LEAVE is the default if you do not specify LEAVE, NEXT, RETRY, or RETURN.

NEXT [ label2 ]

Indicates that, after undoing the processing of a block, the AVM should execute 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 block labeled label1.

RETRY [ label1 ]

Indicates that, after undoing the processing of a block, the AVM should repeat the same iteration of the block that you name with the label1 option.

RETRY is the default if you do not specify of LEAVE, NEXT, RETRY, or RETURN.

RETURN ...

Returns to the calling routine, or if there is no calling routine, returns to the OpenEdge Editor. The following table describes various RETURN cases:


Option	Description
`return-value`	The CHARACTER string you provide is passed to the caller. The caller can use the RETURN-VALUE function to read the returned value.
ERROR	Raises ERROR in the caller and undoes the current subtransaction.
ERROR `return-value`	Raises ERROR in the caller and undoes the current subtransaction. The CHARACTER string you provide is passed to the caller. The caller can use the RETURN-VALUE function to read the returned value. The AVM also creates a `Progress.Lang.AppError` object and stores the `return-value` in the `ReturnValue` property. Note: User-defined functions have different behavior since they must return the data type specified in the definition. See the "FUNCTION statement" section for more information.
ERROR `error-object-expression`	Raises ERROR in the caller and undoes the current subtransaction. The specified error object is created and populated according to your code. If this is an `Progress.Lang.AppError` object, the caller can use the RETURN-VALUE function to read the setting of the `ReturnValue` property.
NO-APPLY	In a user-interface trigger, prevents the AVM from performing the default behavior for that event.

You cannot specify ERROR within a user-interface trigger block or a destructor. You can specify the NO-APPLY option only within a user-interface trigger block.

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.

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.