QuickEvents, Commuter Modules and Passing-By-Reference

As you may (or may not) know variables in Basic+ are passed to stored procedures “by reference”, meaning that if you change a passed variable in the called procedure, that change is reflected in the calling routine (a fuller explanation of how this works can be found here). This behavior is critical to the way many system functions work (such as iconv and oconv) and is very useful in returning more than one item of data from a called procedure.

However, one place where this rule breaks down is when calling stored procedures via a QuickEvent, such as routing an event to a commuter module like so:

Commuter Module QuickEvent

Example: Calling a Commuter Module from a QuickEvent

When you call a stored procedure in this way the system eventually passes your request to a routine called ExecNpHandler() which dispatches the event and its arguments to the desired target,  However at this point the pass-by-reference chain gets broken because a copy of the argument is passed to the stored procedure rather than the original.

For example, if we used Send_Event() to trigger the OMNIEVENT event in the above example, and the commuter module changed Param2, the Send_Event() caller would not see the change (Note that if you use an Event Script handler then passing the event arguments by reference works as you would expect, and you will see changes made to your arguments by the Event Script handler).

While working on the v10 IDE this proved to be something of a problem because the framework relies on a series of OMNIEVENT calls to pass messages between various entities, and sometimes arguments are updated to let the caller know of things like state changes and suchlike.  With something as complex as the IDE, writing the events as a series of Event Scripts was impractical so we took the opportunity to update ExecNpHandler() to respect the pass-by-reference paradigm instead – Now you get to see your changes in a consistent manner regardless of whether you prefer Event Scripts or QuickEvents.

So, is this change likely to impact you? In most cases the answer is no as ExecNpHandler() is normally the last handler to be called in the event chain, and any changes to passed arguments are usually ignored.  Where this might be an issue is when:

  1. You call forward_Event() from an Event Script, or fire an event via Send_Event(), and
  2. You rely on the arguments you passed to either of the above functions remaining unchanged, and
  3. You changed the arguments passed to you in the commuter module, either by carelessness or design.

In this set of circumstances you will probably see an effect, and you may have to modify your code accordingly.

(Disclaimer: This article is based on preliminary information and may be subject to change in the final release version of OpenInsight 10).

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s