Programming Guide : Inter-Frame Communication Techniques : How You Can Communicate with an External Program Using External User Events : UserEvent Event Block
 
Share this page          
UserEvent Event Block
The UserEvent event block for an external user event is the same as the event block for an internal user event. In this event block, you provide the code that is executed when the event is triggered. The syntax follows:
on userevent ['eventname']
begin
    statement list
end;
eventname
Specifies any string of up to 32 characters enclosed in quotes. If you specify the event name, OpenROAD executes the event block whenever the frame receives that particular user event. This name must be the same as the one you use when you register the frame to receive the event with the RegisterUserEvent method as described in RegisterUserEvent Method. The following example illustrates this:
on userevent 'external_update'
begin
    program statement
    program statement
    program statement
end;
If you do not specify an event name, OpenROAD executes the block whenever the frame receives a user event for which there is no specific event block in the frame script. You can specify any number of user event blocks in the frame script, although each must have a unique event name, or no event name at all.
You can discover the name of the event that caused the execution of an unnamed user event block by referencing the EventName attribute of the frame's FrameExec object.
Because external events and the OpenROAD SendUserEvent method both trigger user event blocks, it is preferable to use appropriate naming conventions for your user events. (It cannot be determined within the event block whether the event was triggered by OpenROAD or by an external program.)
The event block for the external event can contain any OpenROAD statements.
How You Can Pass an Integer Value to an Event Block
The IIW4GL_SendUserEvent procedure, which you use in your 3GL program to send the user event, has a messageinteger parameter that you can use to pass one integer value to the user event block. In the receiving frame, OpenROAD stores this value in the MessageInteger attribute of the FrameExec object. To access this data in your user event block, use the CurFrame system variable to reference the current FrameExec.
For more information about this procedure, see IIW4GL_SendUserEvent Procedure.