ON statement

The ON statement specifies a trigger for one or more events or redefines terminal keys for an application.

Syntax


ON `event-list` { ANYWHERE \| { OF `widget-list` [ OR `event-list` OF `widget-list` ] ... [ ANYWHERE ] } } { `trigger-block` \| REVERT \| { PERSISTENT RUN `procedure` [ ( `input-parameters` ) ] } }


ON `event` OF `database-object` [ `referencing-phrase` ] [ OVERRIDE ] { `trigger-block` \| REVERT }


ON `key-label` `key-function`


ON "WEB-NOTIFY" ANYWHERE { `trigger-block` }

event-list

A comma-separated list of user-interface events for which you want to define a trigger. If any of the specified events occurs for any of the specified widgets, the trigger executes.

For a list of valid events for each widget type, see the reference page for that widget type. For information on all user interface events, see the "Handle-based Object Events Reference" section.

widget-list

A comma-separated list of widgets or procedure handles to which the event is applied. See the Widget phrase reference entry for more information on referencing widgets.

If a specified event occurs for any of the specified widgets, the trigger executes. If you specify a list of widgets, all events specified must be user-interface events.

ANYWHERE

You can specify ANYWHERE either with a list of widgets or instead of a list of widgets. Without a list of widgets, ANYWHERE specifies that the trigger executes when one of the specified events occurs for any widget that does not already have a specific trigger for that event. This lets you define a default trigger for the event within the application. With a list of widgets, ANYWHERE specifies that the trigger executes when one of the specified events occurs for any specified widget or for any contained widget that does not already have a specific trigger for that event. This lets you set up a default trigger for a frame or window.

event

A database event: CREATE, DELETE, FIND, WRITE or ASSIGN. If the specified event occurs for the specified table or field, the trigger executes. For database events, you can specify only one event.

database-object [ referencing-phrase ]

The name of a database table or field to which the event is applied. If you specify a database-object, the event specified must be a database event. You cannot specify a metaschema table or field (a table or field named with an initial underscore) as the database-object.

The referencing-phrase is valid only for WRITE and ASSIGN triggers. For WRITE triggers you can specify a name for the record before the WRITE operation and a name for the record after the WRITE operation. This allows you to reference both versions of the record within the trigger. This is the syntax for WRITE trigger:

Syntax
NEW [ BUFFER ] `new-record` OLD [ BUFFER ] `old-record`

For an ASSIGN trigger, you can specify a name for the old field value. This is the syntax:

Syntax
OLD [ VALUE ] `old-field-name`

OVERRIDE

Specifies that the database trigger you are defining overrides the schema trigger for the same event. You can override a schema trigger only if it is defined as overridable in the Data Dictionary. If you do not use the OVERRIDE option, then the session trigger executes first and then the schema trigger.

trigger-block

A trigger block is either a single ABL statement or a set of statements grouped by DO and END statements. The trigger block is executed when one of the specified events is applied to one of the specified widgets or tables.

REVERT

If you specify this option, any non-persistent trigger defined in this procedure for the event is reverted. If a trigger had also been defined for the event in a previous procedure, that previous trigger again takes effect. The AVM ignores any attempt to revert a persistent trigger.

PERSISTENT RUN procedure [ ( input-parameters ) ]

Specifies a persistent trigger; that is, a trigger that remains in effect after the current procedure terminates. Normally, a trigger remains in effect only until the procedure or trigger in which it is defined ends. You can specify a persistent trigger only for user-interface events. A persistent trigger must be a procedure specified by procedure. The trigger procedure can take one or more input parameters; it cannot have any output parameters. The parameters of the trigger procedure are evaluated when you define the trigger; they are not re-evaluated when the trigger executes.

key-label

The label of the key for which you want to define a specific action. See OpenEdge Development: Programming Interfaces for a list of key labels.

On UNIX, all of the special ABL keys are defined in the PROTERMCAP file supplied with ABL. If the key for which you are defining an action is not already in PROTERMCAP, you must add a definition for that key. Keys that you can name that do not require a PROTERMCAP definition are CTRL, RETURN, BACKSPACE, TAB, and DEL.

In Windows, keys are predefined as described in the handling user input section of OpenEdge Development: Programming Interfaces.

key-function

The action you want the AVM to take when the user presses the key associated with key-label. The key-function value can be one of the key functions listed in Table 47.

Table 47: Valid key functions
ABORT	BACKSPACE	BACK-TAB
BELL	CLEAR	CURSOR-DOWN
CURSOR-LEFT	CURSOR-RIGHT	CURSOR-UP
DELETE-CHARACTER	END	END-ERROR
ENDKEY	ENTER-MENUBAR	ERROR
GO	HELP	HOME
INSERT-MODE	LEFT-END	NEXT-FRAME
PREV-FRAME	RECALL	RETURN
RIGHT-END	SCROLL-MODE	STOP
TAB	–	–

Examples

The following example defines a WRITE trigger for the customer table:

r-oncst.p
ON WRITE OF Customer NEW new-cust OLD old-cust DO: IF new-cust.City <> old-cust.City AND new-cust.PostalCode = old-cust.PostalCode THEN DO: MESSAGE "Must update postal code, too.". RETURN ERROR. END. END. FOR EACH Customer: UPDATE Customer. END.

r-oncst.p

ON WRITE OF Customer NEW new-cust OLD old-cust DO: 
  IF new-cust.City <> old-cust.City AND 
    new-cust.PostalCode = old-cust.PostalCode THEN DO: 
    MESSAGE "Must update postal code, too.". 
    RETURN ERROR. 
  END. 
END. 
FOR EACH Customer: 
  UPDATE Customer. 
END.

The trigger compares the Customer record before the write with the Customer record after the write. If the city has changed and the postal code has not changed, the trigger displays a message and cancels the write operation.

The following example uses the ON statement to set up a trigger for two buttons:

r-widget.p
DEFINE BUTTON b_next LABEL "Next". DEFINE BUTTON b_prev LABEL "Previous". DEFINE BUTTON b_quit LABEL "Quit". DEFINE FRAME butt-frame b_next b_prev WITH CENTERED ROW SCREEN-LINES - 1. DEFINE FRAME info Customer.CustNum Customer.Name b_quit AT ROW-OF Customer.CustNum + 2 COLUMN-OF Customer.CustNum + 18 WITH CENTERED TITLE "Customers" ROW 2 1 COL. ON CHOOSE OF b_next, b_prev DO: IF SELF:LABEL = "Next" THEN FIND NEXT Customer NO-LOCK. ELSE FIND PREV Customer NO-LOCK. DISPLAY Customer.CustNum Customer.Name WITH FRAME info. END. ENABLE b_next b_prev WITH FRAME butt-frame. ENABLE b_quit WITH FRAME info. WAIT-FOR END-ERROR OF FRAME butt-frame OR CHOOSE OF b_quit IN FRAME info FOCUS b_next IN FRAME butt-frame.

r-widget.p

DEFINE BUTTON b_next LABEL "Next". 
DEFINE BUTTON b_prev LABEL "Previous". 
DEFINE BUTTON b_quit LABEL "Quit". 
DEFINE FRAME butt-frame 
  b_next b_prev 
  WITH CENTERED ROW SCREEN-LINES - 1. 
DEFINE FRAME info 
  Customer.CustNum Customer.Name 
  b_quit AT ROW-OF Customer.CustNum + 2 COLUMN-OF Customer.CustNum + 18 
  WITH CENTERED TITLE "Customers"  ROW 2 1 COL. 
ON CHOOSE OF b_next, b_prev DO: 
  IF SELF:LABEL = "Next" THEN 
    FIND NEXT Customer NO-LOCK. 
  ELSE  
    FIND PREV Customer NO-LOCK. 
  DISPLAY Customer.CustNum Customer.Name WITH FRAME info. 
END. 
   
ENABLE b_next b_prev WITH FRAME butt-frame. 
ENABLE b_quit WITH FRAME info. 
WAIT-FOR END-ERROR OF FRAME butt-frame OR 
  CHOOSE OF b_quit IN FRAME info FOCUS b_next IN FRAME butt-frame.

The following procedure sets up mappings for GO, HELP, and END and defines CTRL+X to ring the terminal bell:

r-onstmt.p
ON F1 GO. /* F1 will now perform the GO function / ON F2 HELP. / F2 will now perform the HELP function / ON CTRL-X BELL. / The Ctrl-X key will be disabled / ON F5 ENDKEY. / F5 will always raise the ENDKEY condition; never ERROR*/

r-onstmt.p

ON F1 GO.       /* F1 will now perform the GO function */ 
ON F2 HELP.     /* F2 will now perform the HELP function   */ 
ON CTRL-X BELL. /* The Ctrl-X key will be disabled */ 
ON F5 ENDKEY.   /* F5 will always raise the ENDKEY condition; never ERROR*/

Notes

If you use the ON statement to redefine terminal keys, the new definitions remain in effect to the end of the session or until another ON statement changes the definition.

A trigger defined with the ON statement remains in effect until one of the following occurs:

Another ON statement defines another trigger (or REVERT) for the same event and widget

For a non-persistent trigger, the procedure or trigger block in which the ON statement appears terminates

Although each widget type responds with default system actions to a limited set of valid events, you can specify any event for any widget and execute the trigger using the APPLY statement. If the event is not a valid event for the widget type, the specified trigger executes, but no default system action occurs for the widget. You can use this feature to write triggers for procedure handles that do not otherwise respond to events.

If event-list includes a MENU-DROP event for a menu or submenu, do not interact with the window manager from within the trigger-block. Doing so causes the window manager to lose control of the system, forcing you to reboot or restart the window manager. Actions to avoid include any window system input/output (I/O) or any lengthy processing, especially in statements that cause process interruptions, such as the PAUSE statement with or without I/O. These also include actions that can generate a warning or error message, forcing window system output. Use the NO-ERROR option on supported statements to help avoid this situation. Otherwise, check valid values, especially for run-time resources like handles, to prevent the AVM from displaying unexpected messages.

For SpeedScript, the only valid uses of the ON statement are specifying a trigger for a database event or for specifying a trigger for a WEB-NOTIFY event (the ON “WEB-NOTIFY” ANYWHERE syntax).

The ON statement only works with ABL events. You cannot use the ON statement to interact with .NET object events.