COMClient

(Engine-Level Function)

Description:	Instantiates COM objects that do not possess a user interface.
Returns:	COM client interface
Usage:	Script or steady state.
Function Groups:	COM
Related to:	ActiveX \| COMEvent \| COMStatus \| Caller
Format:	COMClient(ObjectIdentifier, ObjectContext, EventSearchScope[, EventParent, EventCaller])
Parameters:

ObjectIdentifier

Required. Specifies a unique identifier for the object to be instantiated. It may take one of the following forms:

a text string representing a ProgID (e.g. "Excel.Application").
a textual GUID, in registry format (e.g. "{00020812-0000-0000-C000-000000000046}").
a binary GUID (e.g. the result from "GetGUID(1, 00020812-0000-0000-C000-000000000046)").

ObjectContext

Required. If valid, this object specifies the contexts in which it is permissible to instantiate the COM object.

A subset of values taken from the CLSCTX enumeration is supported. Possible values are:

CLSCTX_INPROC_SERVER (1): The COM object is instantiated in the VTScada process (i.e. by a DLL).
CLSCTX_LOCAL_SERVER (4): The COM object is instantiated in a separate process (i.e. by an .exe, but only on the same machine upon which VTScada is running.
CLSCTX_SERVER (13): Any of the above. This is the default and permits the COM object to be instantiated wherever the "class factory" (which performs object instantiation) sees fit.

EventSearchScope

Required. May be any expression that yields a module value or object value. This parameter specifies the scope in which to search for event subroutines. If missing or invalid, the COM events will not be enabled.

EventParent

Optional. May be any expression that yields an object value. If present, specifies the context that is used to resolve scope for event subroutines.
If absent or Invalid, defaults to Self().

EventCaller

Optional. May be any expression that yields an object value. If present, specifies an "auxiliary" context for event subroutines. An event subroutine can retrieve this value using Caller(Self()).
If absent or Invalid, defaults to Self().

Comments:

COMClient instantiates a COM object. Generally this statement is used to instantiate COM objects that do not possess a user interface. If the object does display a user interface, then the user interface will appear in a window created and owned by the object. It is more usual to use the ActiveX statement to create a COM object that has a user interface.

If the statement succeeds, a COM client interface is returned, allowing subsequent access to the object. If the statement fails, Invalid is returned.

Arrays indexes are deliberately offset by -1 so that a 1-based array in the object becomes a 0-based array in script.

EventSearchScope specifies the location where the event subroutines for this COM object instance may be found. Each event subroutine is named after the corresponding event produced by the default outgoing interface for the COM object. If the COM object generates an event for which an event subroutine cannot be found, the COM object is informed that event handling for that event is not implemented.

When an event subroutine is run in response to an incoming event from the object, the parent and caller for the subroutine are as specified by EventParent and EventCaller. The event subroutine may update any of its parameters, and any that are defined as [in, out] or [out]. These will be returned to the COM object on completion of the event subroutine. The event subroutine should return an integer value, which is returned to the COM object as the result of the event. A value of 0 indicates the event completed successfully.

If the COM object to be instantiated is an inproc server object (i.e. it is a DLL) then it must be a 64-bit COM server for 64-bit VTScada and a 32-bit COM server for 32-bit VTScada. If it is instantiated out-of-process (i.e. it is an .EXE) then either 32-bit VTScada or 64-bit VTScada can work with either 32-bit or 64-bit COM servers.

If used in a script, the COM object will remain instantiated until the last reference to that object has been invalidated. You assign the return value of the COMClient script statement to a variable, and the COM object will remain instantiated as long as that variable or any other variable holds a copy of the COM Client Interface handle. Only when the last copy of the COM Client Interface handle has been destroyed will the COM object be destroyed.

If used in a steady-state statement, the COM object will only remain instantiated while the steady-state statement is still running. In other words, a change of state or destruction of the module instance that is running the statement will cause the COM object to be destroyed. Any variables that hold a handle to the COM Client Interface will be invalidated at that time.

Example:

{ If writing data to Excel, you will need an Excel COM object... }
Init [
  If 1 Main;
  [
    ExcelIF = ComClient("Excel.Application");
    { check the status: }
    ErrCode = ComStatus(ExcelIF);
  ]
]