Using Commuter Modules


The OpenInsight Form Designer’s event handlers are convenient for rapid development, but become difficult to maintain in a large project.  Arev programmers traditionally use a single program for each window, calling that program from every window or prompt process, passing a parameter to indicate which process to run.  In Arev, we called these programs “commuter modules”.  In today’s buzzwords, you would say that the Arev coders were implementing a model-view-controller design pattern.  This same pattern works well in OpenInsight.

OpenInsight improves upon the Arev event calling method in several ways:  The event model is much richer, so it is easier to detect how and exactly when to respond to events.  You can pass any number of parameters to your event module, so you don’t need to write as much code to guess the current situation.  You have Get_Property and Set_Property to affect the window directly, so it is easier to get exactly the result you want.  Finally, the 64k limit on program size is gone, so you will not need to worry about program size.

OpenInsight includes a QuickEvent, which will call your commuter module.  This lesson will talk about when to use the QuickEvent, when you cannot use it, and how to write a commuter module, which is compatible with the QuickEvent interface.


The "Call Commuter Module" QuickEvent Option

Notice how the parameters are filled in with default values.

Parameter                          Meaning
@SELF                             Current Control
@EVENT                           Current Event
@PARAM1…@PARAM6    Default parameters passed by the event.
 
Some events, for example Click, pass no parameters, others, like Poschanged, pass values.  The OpenInsight event handler will pass the values through to the commuter module in the @param1 parameter, @param2 parameter, etc., etc., etc.

The Commuter Module

The Obj_Call_Event function calls a stored procedure executable with the same name as the OpenInsight Window Executable.   For example, those events sent within the JOB window would call the JOB commuter module.

Function JOB(CtrlEntId,Event,Param1,Param2,Param3,Param4,Param5)
Declare Function Unassigned
Initialize Unassigned Variables
If Unassigned(Param1) Then Param1 = ""
If Unassigned(Param2) Then Param2 = ""
If Unassigned(Param3) Then Param3 = ""
If Unassigned(Param4) Then Param4 = ""
If Unassigned(Param5) Then Param5 = ""
If Unassigned(Param6) Then Param6 = ""

* Set the Return Value
ReturnValue = 0 

* The Body of the Commuter Module 

Begin Case
   Case CtrlEntId _eqc @Window:".JOBS" ; Gosub Search_Jobs
   Case CtrlEntId _eqc @Window:".CITY"; Gosub Search_City
End Case

* Return to the Calling Event
Return ReturnValue

Syntax:

Function JOB(CtrlEntId,Event,param1,param2,param3,param4,param5,param6)

The Obj_Call_Event function will pass the following arguments:

   CtrlEntID – The fully qualified control name.
   Event – The current event. 
   Param1 … Param6 – The parameters passed by the event.

   Experience shows that 6 parameters are sufficient for most situations. 

It is good practice to assign the arguments that have not been passed.  This will avoid Variable Not Assigned Value errors. 

   If Unassigned(param1) then param1 =  ""

The function returns a value.  For a QuickEvent called commuter module the return value should be a 0 since there are no other steps within the event chain.

   ReturnValue = 0

The body of the commuter module is the branch processing based on the control and event.  A Case Statement is useful for this process with Gosub calls to internal subroutines.  The code in the internal subroutines will handle all the events for the control

Begin Case
   Case CtrlEntID eqc @window:” JOBS”; Gosub Search_Jobs
   Case CtrlEntID eqc @window:”.CITY”; Gosub Search_City
End Case

A function requires a Return statement and Return Value.

   Return ReturnValue

Using the Commuter Module for System Events

The example code outlined above works for those events that are the last in the event chain.  If code needs to occur elsewhere in the event chain then the QuickEvent cannot be used, the control’s event handler must be used.  The following is sample code within the event handler for the Read Event of the JOB form

   declare function Obj_Call_Event
   returnValue = Obj_Call_Event(CtrlEntId,"READ")
   return ReturnValue 

This code will call the commuter module and pass through the event chain based on the return value of the commuter module function.

In conclusion, the commuter module functionality can add to the ease of maintenance of applications by separating the event logic from the OpenInsight window and creating a central location for source code behind a window.

Revelation Conference

The previous Revelation Software Users' Conference was held at the Omni Orlando Resort at Championsgate in Orlando, Florida on April 18-21, 2016.

Click Here

On The Road

Throughout the year Revelation Software attends various multivalue User Conferences as well as our Regional User Group meetings.

Click Here

International Offices

Revelation Software has various International Offices and sales regions located on multiple continents.

Click Here

Featured Clients

Revelation Software's clients are involved in every industry around the world. Here is a sampling of some of our clients and their businesses

Click Here