Accessing COM Objects

COM defines standard ways to instantiate an object, regardless of the location of the server code that generates the object instance. An object may be instantiated in-process by a DLL server, out-of-process on the same computer by an EXE server, or on another computer that is also an EXE server. Regardless of the object's location and the method of construction, the syntactic constructs to manipulate the object are identical. VTScada script code that constructs such object instances and manipulates them has no knowledge of the object's location.

A COM object may be identified by a "CLSID" (class ID), comprising a 38-character string that consists of an opening curly brace, a 36-character GUID (Globally Unique Identifier), and a trailing closing curly brace.

 Each application has its own Globally Unique Identifier (GUID), which is generated by VTScada when the application is created. It can be found in the Information page of the Application Configuration dialog.

Internally, the operating system uses the GUID to look-up instantiation information for the specified object in the system registry. This notation is hardly human-friendly however, and so another translation exists, allowing an object to be identified by a "ProgID" (Program ID). The ProgID is then internally translated into a CLSID by the operating system.

A ProgID is a text string typically identifying a server code for associated objects, along with the identity of the object itself (for example, "TrihedralWidgetServer.Widget2" where "TrihedralWidgetServer" is the server code, and "Widget2" is the object).

The look-up information for such translations and the ultimate identification of the location of the object's server is all contained in the system registry, as such information is normally programmatically stored there during the installation process for the object's server.

To create an instance of a COM object, you may use the COMClient statement. This statement takes a parameter representing the CLSID or ProgID of the object to be created (among other items), and assuming that this identifier does indeed map to a COM object, returns a value that may be assigned to a variable. This variable is an opaque handle, termed the "COM Client Interface" and is the only way to subsequently manipulate the object instance.

Manipulation of the object instance occurs via "properties" and "methods". You can think of properties as being the data that the object holds. The automation interface provides a "property get" ability, and a "property set" ability, to allow the properties contained within the object to be manipulated. The automation interface also provides the ability to call object methods.

The distinction between accessing a property and calling a method can sometimes be blurred. For example, it may be that the object implements a method that simply changes or returns the value of an internal property. Some properties may be parameterized; in other words, setting the property value requires more than one parameter to be passed. The syntactic structure of COM calls in VTScada however, conceals such confusions by providing a set of uniform object manipulation operations, where parameters passed to property manipulations are done in a manner identical to those in a method call.

When using a VTable interface (see Introduction to COM), the set of properties and methods, along with their parameter types, are normally expressed in source code form in a header file. However, automation interfaces had such metadata programmatically generated into a binary file called a "type library" when the object's server was built. The VTScada engine uses the type library's metadata to convert between VTScada values and the target object's expected value types, and to locate the correct property or method within the target object. The VTScada programmer can either use the object's formal documentation or one of the various commercially available "type library browsers" to examine the metadata stored in a type library, and hence, discover the methods and properties that the object supports.

Each property get, property set or method call is described in the type library. Each parameter will be described not only by its type, but will also carry a directional specification such as [in] [out] or [in, out]. The directional specification indicates whether the parameter is an input to the instance ([in]), an output from the instance ([out]) or is both ([in, out]). By specifying a non-constant VTScada variable as a parameter for [out] and [in, out] parameters, the VTScada variable value will be updated at the conclusion of the property or method invocation.