Tag Archives: Repository

Insert records and the TCOMPILE method

One style of programming we generally try to avoid is placing executable code statements (*) in a “$insert” record (i.e. an STPROCINS entity) and using that in another program because it usually suffers from the following problems:

  • Inserted code cannot be traced properly with the debugger, making it hard to step through a procedure and possibly obscuring variable initialization and manipulation.
  • Changes to the inserted code will force all the hosting stored procedures to need recompilation.
  • The BLint() process that the compiler uses to check for suspected unassigned variables will not follow the $insert statement and process the insert record, making compile time errors more difficult to detect.

However, whilst working on the new Form Designer we found there was quite a bit of common code that was shared between the various modules used by the form parser and compiler, and we obviously didn’t want to duplicate this in each one.  Normally we would just move the code into a separate stored procedure and call that from each module, but that just adds extra overhead in a process that we really wanted to keep as fast as possible, and so we looked at another option: moving it into an insert record instead. Sharing the code this way means that it runs “inline”, thereby removing the need to create another call-frame, move variables on and off the stack, and so on.

The shared code involved was fairly straightforward, well-tested, and limited to a few small subroutines, so the only real issue to overcome was: how can we easily update any “host” stored procedures in the event of the insert record being changed?

Well, one of the nice things about the OpenInsight repository is that it tracks the various relationships between entities in an application, and some types support a method called TCOMPILE (Tree-Compile) that allows an entity to compile any other entities they are using during the compilation process as well.  However, in this case we needed to do the opposite and compile those entities that were using the insert record instead, and so we created a TCOMPILE method for the STPROCINS type that processes this list of “used-by” entities and executes their normal COMPILE method after the insert record has been saved. This results in a simple way to ensure that changes are implemented across any affected programs.

Whilst we wouldn’t say we exactly endorse embedding programs in this way, it does remain a useful technique for sharing code in some limited cases, and with the new TCOMPILE method it is now much easier to manage too.

(* e.g. code statements such as “x = y + z; call msg( @window, txt );” etc, as opposed to simple constant declarations like equate statements).

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

OLE Control Integration

One of the goals for version 10 is better OLE control (OCX) integration and support.  A major part of that objective is the ability to register OLE controls with the IDE and bind them to the database in a similar fashion to the standard controls such as Edit Lines, Edit Tables and so on. In this post we’ll be taking a brief look at how this new functionality is being implemented.

Registering OLE Controls

OpenInsight 10 supports a new repository type called “OLECONTROL”. This represents an OLE control “registration record” (stored in the new SYSREPOSOLECONTROLS table) which contains basic information, such as its CLSID and description, and the information needed for data binding, such as the name of the OLE property to use for the DEFPROP property.

The simple form below shows the information that can be held for an OLECONTROL entity (Note that this form isn’t final, right now it’s a “bare-bones” version that is being developed further to integrate with the new IDE, but it does allow full testing and validation).

OLE Control Registration

OLE Control Registration

The CLSID

The first, and most critical item of data, is the Class ID (CLSID) of the OLE control, which is a 128-bit number (called a GUID, or Globally Unique IDentifier) that uniquely identifies it. When you install an OLE control onto a system, the CLSID is used as a key in the registry where various bits of information about the control are stored.

Older versions of OpenInsight have always required you to enter the CLSID manually when using OLE controls with the Form Designer, and this can be a tedious task if not provided with the control’s documentation, usually needing a good trawl through your Windows Registry or a special tool like Microsoft’s OLEView to find it. With version 10 we’ve included a new dialog that does the heavy lifting for you when you want a CLSID: It enumerates all the OLE controls that are installed on your system and presents them as a list for you to choose from, returning the CLSID when you click “OK”.

Select OLE Control

Select OLE Control

Once you have specified the CLSID you can save the record without any further input if you wish.  The control won’t be data-bound but it will be added to the tool palette in the Form Designer as a new item so it is readily available for subsequent development purposes.

Data-binding OLE controls

If you wish to support data-binding the next item to specify is the DEFPROP property, which is a “synthetic” property that maps onto a “real” property (such as TEXT, VALUE, ARRAY etc.) at run-time. All data-binding in OpenInsight is handled through the DEFPROP property and it is the sole mechanism by which the form IO layer accesses data in the user interface.

For an OLE control DEFPROP can be mapped in one of two ways:

  1. By specifying an actual OLE property of the control (such as “Text” for example), or,
  2. By specifying the name of a Basic+ handler function that the form IO layer calls to handle the request. This latter method can be useful when dealing with a complex control such as a grid, that might need to insert/delete rows and set cells individually if it doesn’t have something like an intrinsic OpenInsight-style ARRAY property.

If you do specify a Basic+ DEFPROP handler function it must conform to the following interface:

   defPropVal = myDefPropHandler( ctrlEntID, flags, newValue, index )

      ctrlEntID -> ID of the control to get the value for 
      flags     -> Denotes if this is a GET or SET/SETONLY request
      newValue  -> The new value if this is a SET/SETONLY operation
      index     -> Property index:
                       <1> Col
                       <2> Row

Note that the Option (“…”) buttons on the form present a popup of OLE properties and events, or matching Stored Procedures, as appropriate:

Select OLE Property

Selecting an OLE Property for the Web Browser control

Binding multi-column (AMV) controls

If your OLE control can support multiple data columns like the standard OpenInsight EditTable, there are two more items needed to allow the form IO layer to understand how to use your control:

  1. The new DEFPOSPROP property, and
  2. The name of an OLE event that maps to the equivalent of OpenInsight’s POSCHANGED event.

The DEFPOSPROP property is used to access the current column/row/cell position within the control, in a similar fashion to the standard SELPOS or CARETPOS properties.  It can be mapped in one of three ways:

  1. By specifying a single actual OLE property of the control (such as “SelPos” for example) that implements an @fm-delimited column and row index format (like CARETPOS)
  2. By specifying a comma delimited pair of properties representing the column and row positions respectively, e.g. “CurrCol,CurrRow”
  3. By specifying the name of a Basic+ handler function that the form IO layer calls to handle the request in a similar fashion to the DEFPROP handler.

A Basic+ DEFPOSPROP handler should have the following interface:

   defPosPropVal = myDefPosPropHandler( ctrlEntID, flags, newPos )

      ctrlEntID -> ID of the control to get the value for 
      flags     -> Denotes if this is a GET or SET/SETONLY request
      new       -> The new position if this is a SET/SETONLY operation
                       <1> Col
                       <2> Row

  defPosPropVal <- Returns the current position in the format:
                       <1> Col
                       <2> Row

The final item needed is the POSCHANGED event name so that the form IO layer can check when data has been entered into a cell for validation and update purposes.

Control Semantics

The next set of information is used by the Form Designer to indicate what extra features it needs to present when the OLE control is being edited:

  • Allow Data-Binding: Checking this box tells the Form Designer to allow TABLE and COLUMN properties to be entered.  This must be set if you wish to actually bind your control to the database at runtime.
  • Required Support: Checking this box tells the Form Designer to allow the REQUIRED property to be specified.
  • IConv Support: Checking this box tells the Form Designer to allow the VALID property to be specified.
  • Oconv Support: Checking this box tells the Form Designer to allow the CONV property to be specified.

CLICK Event Data-Binding

Some controls, such as Checkboxes, update their data when clicked rather when they lose focus or change cell position. In this case the form IO layer needs to know the name of the OLE event to track if the control exhibits this behavior and this should be entered here.

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

Promoted Events and the Repository

One of the most powerful programming features of OpenInsight is the “Promoted Event” model, allowing you to write “global” event handing code that can be triggered for a variety of situations, such as for all objects of a certain type, or for all objects in an application, and so on.  This helps to centralize your code-base and restrict unnecessary duplication, thereby making development faster and more robust.

However, promoted events have also been one of the most opaque parts of the system and  their use is somewhat awkward and error-prone because they rely on the dark art of naming conventions and manual record copying between tables.  In an effort to rectify this we’ve integrated them into the OpenInsight Repository so they can be tracked properly and you can see at a glance exactly what is in your system.  

Promoted events fall into one of 5 generic categories:

 Category                         Example SYSREPOSEVENTS key
 ========                         ==========================
 1) EVENT/CLASS/TYPE specific  -> SYSPROG*ACTIVATED.WINDOW.OIWIN*
 2) EVENT/TYPE specific        -> SYSPROG*ACTIVATED..OIWIN*
 3) TYPE specific              -> SYSPROG*..OIWIN*
 4) EVENT/CLASS specific       -> SYSPROG*ACTIVATED.WINDOW*
 5) EVENT specific             -> SYSPROG*ACTIVATED*

So to enable their integration we’ve added three new entity types:

  • PROMOTEDEVENT (source code)
  • PROMOTEDEVENTDBG (debugger symbol table)
  • PROMOTEDEVENTEXE (object code)

Each of these types has a Repository key structure that derives from the actual promoted event key itself like so:

 SYSREPOSEVENTS key                 Repository key 
 ==================                 ==============
 SYSPROG*ACTIVATED.WINDOW.OIWIN* -> SYSPROG*PROMOTEDEVENT*ACTIVATED*WINDOW.OIWIN
 SYSPROG*ACTIVATED..OIWIN*       -> SYSPROG*PROMOTEDEVENT*ACTIVATED*_.OIWIN
 SYSPROG*..OIWIN*                -> SYSPROG*PROMOTEDEVENT*_*.OIWIN
 SYSPROG*ACTIVATED.WINDOW*       -> SYSPROG*PROMOTEDEVENT*ACTIVATED*WINDOW
 SYSPROG*ACTIVATED*              -> SYSPROG*PROMOTEDEVENT*ACTIVATED*_

Some of you may look twice at the use of the “_” character for the CLASSID and ENTID Repository key parts:  This is actually used as a placeholder to denote a null part in the promoted event key itself – their use is necessary because the Repository reacts poorly to a null CLASSID or ENTID.

We’ve also added a new stored procedure called SYNCH_REPOS_PROMOTED_EVENTS which can scan your SYSREPOSEVENTS and SYSREPOSEVENTEXES tables to create any missing  entities so it’s easy to bring your existing promoted events into the Repository,

Of course integration with the Repository isn’t the end of the story – now that promoted events are recognized as first-class citizens we need to provide the tools in the IDE to create and maintain them… but that’s a story for another time…

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