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