1. Home
  2. COM add-in

COM add-in

Component Object Model (COM) add-ins are supplemental programs that provide additional functionality in a variety of programming languages, including Visual Basic, Visual C++, and Visual J++. Within Genstat this can be used to create dialogs to run a set of Genstat commands.

COM is a binary and network standard that allows any two components to communicate regardless of what device they are running on (as long as the devices are connected), what operating systems the devices are running (as long as they supports COM), and what language the components are written in.

Genstat ICustomConnect Interface

Genstat provides an interface (ICustomConnect interface) containing a group of functions or methods that Genstat calls when an add-in is connected. The ICustomConnect interface contains pre-configured procedure templates (which include their parameter lists) that you use to manage add-ins in Genstat.

The ICustomConnect interface currently contains the following methods:

  • AddInConnect
  • AddInDisconnect
  • AddInUpdate

To enable commands to be received in Genstat via COM, Genstat implements COM event handling. There is a second interface called _ICustomConnectEvents available that can be set up as an event source.

The _ICustomConnectEvents interface contains one method:

  • RunCommand

To use ICustomConnect interface you need to create a COM server (a binary DLL or EXE) that contains a coclass (component object class) that implements the interface. The COM server must be registered in Windows in the standard way.


The Object Definition Language (ODL) syntax for the ICustomConnect interface is as follows:

// ICustomConnect
    dual, helpstring(“ICustomConnect Interface”),
__interface ICustomConnect : IDispatch
    [id(1), helpstring(“method AddInConnect”)] HRESULT AddInConnect([in] HWND hwndParent, [in] LONG lStartup, [in] LPSAFEARRAY *lpArray);
    [id(2), helpstring(“method AddInDisconnect”)] HRESULT AddInDisconnect([in] LONG lExit);
    [id(3), helpstring(“method AddInUpdate”)] HRESULT AddInUpdate([in] LPSAFEARRAY *lpArray);

// _ICustomConnectEvents
    helpstring(“_ICustomConnectEvents Interface”)
__interface _ICustomConnectEvents
    [id(1), helpstring(“method RunCommand”), source] HRESULT RunCommand([in] BSTR bstr, [in] LONG lFile);


Occurs when an add-in is connected to Genstat at start-up or when accessed off the User menu.


AddInConnect(HWND hwndParent, LONG lStartup, LPSAFEARRAY *lpArray)

Parameter Description
hwndParent HWND: for Genstat
lStartup LONG: 0 for startup and 1 for connection from User menu
lpArray LPSAFEARRAY: safe array containing the names and types of Genstat data structures


Occurs when an add-in is disconnected from Genstat on exit.


AddInDisconnect(LONG lExit)

Parameter Description
lStartup LONG: 1 for disconnection from Genstat


Enables data identifier names to be updated within the COM add-in and is called each time there are new or changes to names of data structures.


AddInUpdate(LPSAFEARRAY *lpArray)

Parameter Description
lpArray LPSAFEARRAY: safe array containing the names and types of Genstat data structures


Enables Genstat commands to be sent to Genstat via an event source. Commands can be sent within a BSTR or within a file.


RunCommand(BSTR bstr, LONG lFile)

Parameter Description
bstr BSTR: string containing Genstat commands or the name of a file containing the commands
lFile LONG: 0 if commands sent in BSTR or 1 if a file name is supplied

Attaching to Genstat

To attach a COM add-in to Genstat you must supply the details within a Genstat add-in (GAD) file. Within the GAD file each add-in is specified in a separate section called [AddInX] where X is a number. If you have more than one add-in you can specify these in the same file (as AddIn1, AddIn2, etc…) or within separate files. The details of the add-in are then supplied using different subsections. For example, SUBSECTION = …details…

The type of add-in, in this case the COM add-in, should be supplied using a subsection called Type. Each add-in needs to be supplied a unique ID using the ProgID subsection. This is required so that Genstat can easily distinguish between different add-ins. This can be supplied as a string of characters. Finally the name that is to appear on the User menu should be supplied using the subsection MenuTitle. The following example shows the layout of a GAD file that can be used to attach a COM add-in.

    MenuTitle=My COM add-in

COM add-ins can be grouped together under a menu item using a Submenu subsection in the GAD file. The following example shows the layout that can be used to attach 2 dialogs under the same menu section called New Add-ins.

    MenuTitle=My COM add-in 1
    Submenu=New Add-ins

    MenuTitle=My COM add-in 2
    Submenu=New Add-ins

To make the add-ins accessible from Genstat you must create the GAD file using the file extension .gad. You should then place the file in either the system or user add-in directory. To make a custom menu add-in available system wide, i.e. to all users that have access to Genstat on a network server or on a local machine, you must place the file in the system add-in folder called AddIns within the Genstat installation. Alternatively, to make the custom menu add-in only available to the current user, you can place the file within the user add-in folder. The location of the user add-in folder is controlled by selecting Tools | Options then setting a file path in the User add-in folder field on the General tab.

Updated on May 8, 2019

Was this article helpful?