Event Signaling Service

Event Signaling Service

Applies to Windows and WAM.

The Framework manager provides a simple to use event signaling service that may be used in Windows or Web browser applications:

Refer to tutorial VLF013WIN - Signaling Events or VLF013WAM - Signaling Events for step-by-step instructions of how to use signalling.

When something significant happens in your filter or command handler you may choose to signal an event to other active filters or command handlers so that they can take appropriate action. 

To make event-processing work you need two things:

• A filter or command handler needs to signal the event.  This is called publishing the event.

• Other filters or command handlers need to listen for the event.  This is called subscribing to the event. 

Additional information may be sent along with the event. This is called the payload.

To publish an event in a Windows application you use the method avSignalEvent. For example: 

Invoke #Com_owner.avSignalEvent WithId(Employee_Deleted) SendAInfo1(#EMPNO)

This example signals an event identified as "Employee_Deleted".  It includes the current value of field #EMPNO as additional payload string 1, presumably to identify the employee that has been deleted.   

To subscribe to (or listen for) an event in a Windows application you need to have an EvtRoutine in your filter or command handler.  To do this you listen for an avEvent signal like this example:

EvtRoutine Handling(#Com_owner.avEvent) WithId(#EventId) WithAInfo1(#AInfo1)

   If '#EventId.Value = Employee_Deleted'

       Change #EMPNO #AInfo1.Value    

       << Handle the event >>
   Endif

Endroutine

This example specifically subscribes to the event identified as the "Employee_Deleted" event. The payload protocol used for this event says that the employee number will be received in payload additional information string 1.

In WAM Applications

To publish an event in a WAM application you use the method avSignalEvent. For example:

Invoke #ThisHandler.avSignalEvent WithId(UPDATE_LIST_ENTRY) SendAInfo1(#EMPNO)

To subscribe to (or listen for) an event in a WAM application you need to first register the event like this example;

Invoke Method(#avFrameworkManager.avRegisterEvent) Named(UPDATE_LIST_ENTRY) Signalaswamevent(2)

Then add an event handler as in the following example;

Evtroutine Handling(#avFrameworkManager.uWAMEvent_2) Withid(#eventid) WithAinfo1(#Ainfo1) Options(*noclearmessages *noclearerrors)

If '#EventId.Value = Update_List_Entry'

Change #EMPNO #AInfo1.Value
fetch #xg_ident pslmst with_key(#empno)

* Set up the visual Identifier(s)

#UF_VisID1 := #EMPNO
#UF_VisID2 := #SURNAME
Use BConcat (#UF_VisID2 #GIVENAME) (#UF_VisID2)

* Add instance details to the instance list

Invoke #avListManager.AddtoList Visualid1(#UF_VisID1) Visualid2(#UF_VisID2) AKey1(#EMPNO)
Endif

Endroutine

• Having events flying around in your application impacts its performance. You need to assess this impact in an environment that reflects your worst-case deployment environment. Make sure that you do not use too many events or do too much processing when handling an event. Your event model needs to fit into the resource that you have available to execute it in. This applies doubly to Web browser applications where event handling causes client-server interactions to occur.

• The basic payload that can be sent along with an event allows for up to 5 alphanumeric strings and 5 numeric values. If this is not enough or if you want to send lists of information use the virtual clipboard. The shipped Programming Techniques application contains an example of sending lists of information along with an event by using the virtual clipboard.   

• You should think about a simple and consistent naming standard for your events. Do not use event identifiers that contain periods (".") to avoid conflicts with events issued by the Framework. Avoid special characters that may cause code page issues with different execution platforms. 

• Look at the shipped "Programming Techniques" application for examples of how to code and use events in Web browser applications.

For more detailed information about event handling see:

• avSignalEvent

• #Com_owner.avEvent