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.
Syntax
The Object Definition Language (ODL) syntax for the ICustomConnect interface is as follows:
// ICustomConnect
[
object,
uuid(“E86C8105-1BB7-47A1-B92B-CC80A6B86EFF”),
dual, helpstring(“ICustomConnect Interface”),
pointer_default(unique)
]
__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
[
dispinterface,
uuid(“B2211EB3-0507-49E6-9794-7CEBD792AE27”),
helpstring(“_ICustomConnectEvents Interface”)
]
__interface _ICustomConnectEvents
{
[id(1), helpstring(“method RunCommand”), source] HRESULT RunCommand([in] BSTR bstr, [in] LONG lFile);
};
AddInConnect
Occurs when an add-in is connected to Genstat at start-up or when accessed off the User menu.
Syntax
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 |
AddInDisconnect
Occurs when an add-in is disconnected from Genstat on exit.
Syntax
AddInDisconnect(LONG lExit)
| Parameter | Description |
| lStartup | LONG: 1 for disconnection from Genstat |
AddInUpdate
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.
Syntax
AddInUpdate(LPSAFEARRAY *lpArray)
| Parameter | Description |
| lpArray | LPSAFEARRAY: safe array containing the names and types of Genstat data structures |
RunCommand
Enables Genstat commands to be sent to Genstat via an event source. Commands can be sent within a BSTR or within a file.
Syntax
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.
[AddIn1]
Type=COM
ProgID=MyProgID
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.
[AddIn1]
Type=COM
ProgID=MyProgID1
MenuTitle=My COM add-in 1
Submenu=New Add-ins
[AddIn2]
Type=COM
ProgID=MyProgID2
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.