The COMMUTERMODULE Property

As most of you will probably know, "commuter module" is the term given to a stored procedure whose main purpose is to handle event processing for a specific form.  Rather than have each individual event processed in a separate event script, quick-events are used instead to call the commuter module directly, passing it various parameters such as the name of the object firing the event, the name of the event itself, and any relevant arguments.  The commuter module then branches off to different internal subroutines to handle the event. Following this methodology offers several important advantages:

• Simplified code management
• Simplified deployment
• Improved code sharing via internal subroutines
• Lower memory overhead (single procedure vs. multiple event scripts)

While using a commuter module like this is the recommended way of developing applications in OpenInsight, there has never been any sort of formal link between the commuter module and the form itself, which means that it is usually necessary to adopt a naming convention for this approach to work. For example, it is common to have a commuter module with the same name as the form, or with the same name as the form and suffixed with the string "_EVENTS".  By doing this it was easy to define quick-events to call the commuter module in the old v9 Form Designer like so: [caption id="attachment_2670" align="aligncenter" width="578"] v9 Commuter Module Quick Event[/caption] The OBJ_CALL_EVENT program looks for a stored procedure with the same name as the form, or one with the same name as the form and suffixed with "_EVENTS".  It was also possible to avoid the overhead of a lookup and call the commuter module directly by using the "@WINDOW" placeholder like this: [caption id="attachment_2680" align="aligncenter" width="578"] v9 Commuter Module Quick Event (using @WINDOW)[/caption] Or the "@WINDOW_EVENTS" placeholder like this: Of course, even with this approach the form still wasn't actually linked to it's commuter module, rather it was only linked to "OBJ_CALL_EVENTS" or a fictitious entity called "@WINDOW". In version 10 we've added a new WINDOW property called COMMUTERMODULE, which simply contains the name of the stored procedure to use (this can be any valid name - you are no longer limited to one based on the name of the form, though we do suggest you keep this convention to help organize your application): [caption id="attachment_2706" align="aligncenter" width="782"] CommuterModule Property[/caption] When the form is saved and compiled this stored procedure is linked to the form with a "used-by" relationship, thereby making deployment easier as you will see the link when you create your RDK definition records. Another benefit of this is that you can quickly open your commuter module from the form by using the "View Commuter Module" button on the Form Designer toolbar: [caption id="attachment_2713" align="aligncenter" width="782"] View Commuter Module button[/caption] Finally you can easily set your quick events to call your commuter module in the Event Designer like so: [caption id="attachment_2718" align="aligncenter" width="414"] Commuter Module QuickEvent[/caption] Note that it uses an "@COMMUTER" placeholder - this is replaced with the contents of the COMMUTERMODULE property at runtime. (You can still use the previous @WINDOW/_EVENTS or Obj_Call_Events methods if you wish - those options still exist.) So, this is the first step in tightening the relationship between a form and it's commuter module.  There is certainly scope for more integration between the two and this is something that we hope to pursue during subsequent releases. (Disclaimer: This article is based on preliminary information and may be subject to change in the final release version of OpenInsight 10)

Hi M@,

It all depends on the event :)

It's difficult to change the older events because this might break an existing system. E.g. your READ quick-event is in reality a POST-READ process, but if move the code around to call it first then it becomes a PRE-READ process and that could really screw things up (of course we could have other options to control/mitigate this but I digress…)

New events that have been added to v10 tend to favour commuter modules. There is code in them that explicitly calls into the quick-event handler before taking any further "default" action.

For example, if you look at the new CONTEXTMENU quick event - it's sole purpose is really to display the menu - so it calls the quick event first before it does so - therefore it gives you time to change or block it in your commuter module if you wish. The old CLOSE event also works like this - that's why you can use Set_EventStatus to block a window from closing in your commuter module.

(Having said that I've updated the old VALIDERR and REQUIRERR events to do this too - they use to just call the SYSMSG handler, but now you can intercept validation and required error events, which were never really exposed before, so they are hard to break :)

So, bottom line is .. it depends. Probably the best way forward is to drop us a line about what you want to do and we can tell you what your options are?

Regards

Carl

Is there a way for a commuter program to perform pre system event handling? Ie Do stuff before calling Forward_Event() down the chain. Or does this still need to be done via event scripts or promoted events?