Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## 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 "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. For more information on these events, see OpenEdge Development: Progress 4GL Handbook .

> ``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 4GL 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. Progress 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 Progress keys are defined in the PROTERMCAP file supplied with Progress. 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 Progress to take when the user presses the key associated with `key-label.` The `key-function` value can be one of the following:

> ABORT | END | LEFT-END
> BACKSPACE | END-ERROR | NEXT-FRAME
> BACK-TAB | ENDKEY | PREV-FRAME
> BELL | ENTER-MENUBAR | RECALL
> CLEAR | ERROR | RETURN
> CURSOR-DOWN | GO | RIGHT-END
> CURSOR-LEFT | HELP | SCROLL-MODE
> CURSOR-RIGHT | HOME | STOP
> CURSOR-UP | INSERT-MODE | TAB
> DELETE-CHARACTER |  |

> 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.postal-code = old-cust.postal-code
>          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.cust-num customer.name
>       b_quit AT ROW-OF customer.cust-num + 2 COLUMN-OF customer.cust-num + 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.cust-num 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 widget handles, to prevent Progress 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).

> #### See also

> APPLY statement, Widget phrase

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095