ActiveX Automation Interface

The DataView Server addresses the ActiveX Automation Interface with the help of three new (C language) API functions, dal_gfi_ole_cre, dal_gfi_ole_cal and dal_gfi_ole_del. dal_gfi_ole_cre takes care of starting up the COM server (the application), creates a COM object and assigns it a reference name. The reference name is needed to identify the COM object to the DataView server, and to enable communication via strings between the server and client. dal_gfi_ole_cal uses a complex automation command to call a COM interface's methods and access or modify its properties. dal_gfi_ole_del deletes the COM object when it is no longer needed.


Creating and Deleting COM Objects

You create and delete COM Objects with dal_gfi_ole_cre and dal_gfi_ole_del.

DtvLong dal_gfi_ole_cre (app, nam, res, len)
starts COM server specified by the Application ID, creates a COM object and assigns it a reference name.

Input Parameters char *app -> Application ID with/without version number
char *nam-> Reference name for COM object
Output Parameters char **res -> Result string
dtvlong *len -> Length of result string
Return Value 0 -> OK
~0 -> Error code (-> see Handling Errors)

The Application ID specifies the COM server, and is recorded in the Windows registry. Typical Application IDs can have the form "Application.Document", where "Application" is the name of the application. The ID may also contain the version number, e.g. "Application.Document.6", which could be useful if more than one version of an application is installed.

It is not generally possible to establish contact with a COM server once it is started.

The reference name identifies the COM object to the programme on the DataView server, and must conform to certain -> Naming conventions.

The result string contains the return value in the form "O:COM Class name", or an -> error message.

DtvLong dal_gfi_ole_del (nam)
Deletes a COM object and closes the connection with the COM server. The server is free to decide whether or not to quit automatically.

Input Parameters char *nam -> Reference name for COM Object
Output Parameters none
Return Value 0 -> OK
~0 -> Error code (-> see Handling Errors)


Calling the COM interface's methods

You execute methods or access and alter properties with dal_gfi_ole_cal. This function passes a complex -> Automation Command (a string) to the COM interface. The string must contain the method calls and the reference name of the COM object. This makes it possible to chain calls together and make assignments within a call. Since the COM object determines the return type for a call dynamically at runtime, both the type and the value are returned to the DataView server packaged in a string.

DtvLong dal_gfi_ole_cal (cmd, res, len)
Passes an automation command to the COM interface, where it generates method calls or property accessors and returns a result.

Input Parameters char *cmd -> Automation command
Output Parameters char **res -> Result string
dtvlong len -> Length of result string
Return Value 0 -> OK
~0 -> Error code (-> see Handling Errors)

Automation commands must obey a specific -> command syntax.

The result string contains the value returned by the call in the form "Type:Return value" or an -> error message. The type is either one of the standard DataView types or an additional type 'O', to allow the return value to be a COM object (in which case the stringized return value is the COM class name). If method parameters are returned, they are concatenated in the order they appear in the method's definition, separated by null: "Type1:Return value10Type2:Return value20 ... TypeN:Return valueN00".