On()

On, Comet! On, Cupid! On Donder and Blitzen!
Clement Moore, A Visit From St. Nick, 1823

A number of commands in FoxPro let you set up "event handlers" using statements that begin with ON, then tell what the event is, and then contain a command to execute in that case. For example, ON ERROR DO ErrHand or ON KEY LABEL F1 HELP. This function lets you find out what those event handlers are. The most common reason to do so is to save the current value so you can replace it temporarily and then restore it.

Usage

cCurrentHandler = ON( cHandler [, cKeyName ] )

Parameter	Value	Meaning
cHandler	Character	The second word of the ON command whose current setting should be returned. For example, "ERROR", "KEY". For ON KEY LABEL, use "KEY".
cKeyName	Character	For ON KEY LABEL, the key or key combination whose current setting should be returned.

For everything but ON KEY LABEL, using ON() is pretty straightforward. You just ask for ON("whatever"), like ON("ERROR"). For ON KEY LABEL, you have to specify which key you're interested in, like ON("KEY","F1").The legitimate values for cHandler are: APLABOUT, ERROR, ESCAPE, KEY, MACHELP, PAGE, READERROR and SHUTDOWN. It turns out you can pass any character value at all without an error. If it's not a legitimate value for cHandler or if the specified handler hasn't been set, ON() returns the empty string.

There's a trap here because misspelling the value for cHandler can lead you to believe there isn't one in effect. For example, if you write ON("ERR"), you get back the empty string and you may think this means there's no error handler in effect. You need to specify ON("ERROR") to get the error handler. We can see why they did it this way. It's much more forgiving and probably easier to add to in the future if new handlers come along, but it means you need to double-check your use of ON().

Example

* Save then restore the current error handler
cHoldError = ON( "ERROR" )
ON ERROR DO MyNewErrorHandler
* do some processing
* now restore it
ON ERROR &cHoldError