Promoted Events

Introduction

Although Promoted Events are a natural part of the OpenInsight architecture, developers have been slow to incorporate them as standard operating procedure. In large part this has been due to a lack of formal documentation and tools from Revelation Software to use them. While most of these limitations have been addressed with later releases of OpenInsight, SRP FrameWorks has incorporated them so seamlessly that the developer doesn't even need to know that they exist. However, developers should read this page to gain a better understanding of the SRP FrameWorks architecture.

Purpose of Promoted Events in SRP FrameWorks

There are various types of Promoted Events that can be implemented within OpenInsight. For reasons detailed below, SRP FrameWorks only implements a small handful. This document cannot cover the entire subject of Promoted Events adequately. Therefore, for any who wish to become fully acquainted with Promoted Events we recommend our white paper on this subject. Fortunately, this is not necessary in order to utilize their benefits within SRP FrameWorks.

Traditionally, Promoted Events are implemented as a way to enable application wide functionality without the need to update every event handler. This is also true for SRP FrameWorks. However, Promoted Events are also used as a way to restructure the event chain to give the developer great convenience and more control over event handling. Below is a simple diagram of how event handling gets processed within SRP FrameWorks:

The objective here is to allow more specific event handling (i.e. from within the Commuter Module) to execute first and then move forward to the more generic event handling. Please keep in mind that the actual event flow is a bit more complicated. However, this complexity is efficiently packaged so that the above outline is all that the developer has to experience.

Promoted Event Shells

All procedural event handlers, whether Script, Promoted, or System, are compiled functions stored in the SYSREPOSEVENTEXES system table. This introduces two challenges for developers who want to implement Promoted Events. First, there is no built-in utility that allows the developer to create and modify Promoted Event handlers directly in this table. Indirect methods (which are outlined in our aforementioned white paper) must be used to create or modify items in SYSREPOSEVENTEXES. The second problem is that, due to caching, changes to Promoted Event handlers in SYSREPOSEVENTEXES are not detected by the system until OpenInsight is restarted. Therefore, SRP FrameWorks puts a minimal amount of information in the actual Promoted Event handler. Instead, each handler calls a regular stored procedure (the Promoted_Events function) to manage the actual Promoted Event functionality. Thus, the Promoted Event handlers themselves are merely shells which can be left alone once they are in place.

Since there is no way to create a Promoted Event handler directly, SRP FrameWorks begins with a regular function and then has the object code copied to SYSREPOSEVENTEXES. For the most part, all of the Promoted Event handlers are designed the same way. Here is how one of these functions are structured:

Function FrameWorks_OIwin(CtrlEntId, CtrlClassId, Param1, Param2, ..., Param15) 
     
 $insert APP_INSERTS 

 Declare function Promoted_Events, Get_Current_Event 

 // Enter the following into the Exec line whenever this event gets updated: 
// RUN COPY_ROW "SYSOBJ", "$FRAMEWORKS_OIWIN*FRAMEWORKS", "SYSREPOSEVENTEXES", "FRAMEWORKS*..OIWIN*", "2" 

Event = Get_Current_Event() 

 Return Promoted_Events(CtrlEntId, Event, Param1, Param2, ..., Param15)

Here is a description of the relevant portions of the Promoted Event handlers:

Pre-Installed Promoted Event Handlers

As noted above, there are many types of Promoted Event handlers. SRP FrameWorks is able to eliminate the need for the majority of them by using an application level Promoted Event (as opposed to multiple control-type or event-type Promoted Events.) However, application level Promoted Events can only be executed after the System Event handler. To remedy the need to execute Promoted Event handlers before the System Event handler, a small number of control-type Promoted Event handlers have been created. Here is an inventory of the pre-installed Promoted Event handler functions:

Adding Promoted Event Handlers

As already noted, the application level Promoted Event handler automatically promotes all events. However, there might be a need to add a new control type or event type Promoted Event handler in order to prevent or control how the related System Event handler executes. For example, a developer might want to halt the validation of data being entered into a control. This is handled by the LOSTFOCUS System Event handler therefore a LOSTFOCUS Promoted Event handler would need to be created. Our aforementioned white paper goes into detail on how to create a new Promoted Event handler. However, to make this easier, the developer should use an existing SRP FrameWorks Promoted Event function as a starting point.

Promoted_Events Function

As documented above, all of the Promoted Event handlers call the special Promoted_Events function to eliminate the difficulty of managing dynamic logic directly within the actual Promoted Event handler itself. This function is documented in the Promoted_Events Reference page and it is heavily documented within the function itself.

Although this routine is called by the actual Promoted Event handlers, it really serves as a gateway to other routines. That is, none of the application specific logic gets executed within the Promoted_Events function. Rather, this routine automatically calls other functions which are event specific. These event specific functions use the following naming convention: Promoted_EventName_Event. All of them follow the same code structure:

Function Promoted_Activated_Event(CtrlEntId, Event, Param1, Param2, ..., Param15) 

 $insert APP_INSERTS 
$insert EVENT_SETUP 

 If Event[-3, 3] EQ "PRE" then 
// This is a pre-system handler promoted event. 
GoSub Pre 
end else 
// This is a post-system handler promoted event. 
GoSub Post 
end 

 // If ventFlow hasn't already been assigned then assume it should continue 
If Assigned(ventFlow) else EventFlow = EVENT_CONTINUE$ 

 Return EventFlow 

Pre: 
// All pre-System Event handler logic (if applicable) goes here. 
return

Post: 
// All post-System Event handler logic (if applicable) goes here. 
return

In the above example, the function is specific to the ACTIVATED event. Beyond that, all Promoted_EventName_Event functions work in the same way. What should be emphasized is the fact that these routines share the exact same Signature Line and Return Line as our Commuter Modules. As explained previously, this is done intentionally to create a consistent and efficient method for event management. When this design approach is adopted and applied in all event handler extensions, there is a smooth transition up and down the event chain with the ability to interrupt the chain at every transition point.

A technically more accurate picture of the event chain now looks like this:

Thus, after the Promoted Event handler calls the Promoted_Events function, a check for FormName_Events (i.e. the Commuter Module) is made and then a check for for Promoted_EventName_Event is made. If either one exists then they are called dynamically. Conversely, if either one doesn't exist then it obviously can't be called. Therefore, even though all events in SRP FrameWorks are promoted (and thus the Promoted_Events function will get called), only those events with a corresponding Promoted_EventName_Event function will do anything. SRP FrameWorks ships with the following functions pre-installed:

Adding Promoted_EventName_Event Functions

Most SRP FrameWorks developers soon discover the need to add new Promoted Events functionality. Fortunately, due to the dynamic method used to find Promoted Event specific functions, all the developer needs to do is create a new function using the proper naming convention. From that point forward, SRP FrameWorks automatically calls it whenever that particular event is triggered. Our recommendation is to take an existing function with minimal event specific logic and copy it. The Promoted_Inactivated_Event function is a good example for this.