Previous Next

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 48.
 
Examples 
The following example defines a WRITE trigger for the customer table:
 
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:
 
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:
 
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 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.
*
*
See also 
APPLY statement, Widget phrase

Previous Next
© 2013 Progress Software Corporation and/or its subsidiaries or affiliates.