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 or developer 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.

In batch mode (running with the -b startup parameter) and when running on an application server, the ON statement supports only the following events:
  • PROCEDURE-COMPLETE
  • READ-RESPONSE
  • CONNECT
  • Developer events (U1 to U10, and CLOSE)

    The ten miscellaneous developer events (U1 to U10) have no standard meaning or action. They are reserved for an ABL developer to use for associating a trigger with some event that only happens programmatically using the APPLY statement. They have nothing to do with a particular user action and have no built-in significance. The CLOSE event has these same characteristics and only occurs when specified with the APPLY statement.

    OpenEdge clients running in batch mode process these events just like non-batch clients do.

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:

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:

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 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 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 the following table.
Table 1. 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.

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.

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*/

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.

See also

APPLY statement, Developer events, Handle-based Object Events Reference, WAIT-FOR statement (ABL only), Widget phrase