COM Integration

Requires Analytica Enterprise, Optimizer or ADE.

Analytica supports the Microsoft Component Object Model (COM) as a standard way to communicate with other Windows applications that support COM within the Windows operating system. These include all Microsoft Office applications, including Excel, and many other Windows applications. Analytica's support for COM lets your model call other applications that have a COM automation interface (known as the IDispatch interface). This means that your Analytica model can do just about anything with Microsoft Excel that you might want. You can also write your own COM server in C++, C#, VB, and a host of other languages to add new functions to Analytica.

This feature lets allow your Analytica model call other applications to provide or obtain information But it doesn't let other COM applications call Analytica. For that you must use ADE.

COMCreateObject(name, server, flags, user, password)

The first step when using COM is to instantiate a COM object, which is done using the function COMCreateObject (note: You can also obtain an Excel::_Workbook object using SpreadsheetOpen, which can be used as a COM object). Only the first parameter is required, and it is rare that you would need to worry about the remaining parameters.

Parameters:

«name»

The textual name of the COM class being instantiated. This can be a name such as "WScript.Shell" or "ADE4.CAEngine", or it can be a clsid such as "clsid:72C24DD5-D70A-438B-8A42-98424B88AFB8".

«server»

(optional text) The name of the computer where the object will run. Allows remote invocation, or can be "localhost".

«flags»

(optional integer bitfield). Additional esoteric flags (see the CLSCTX enumeration in Microsoft documentation). These can be added together. Some notable flags are:

0x1 = Allow in-process component (but be same bit-ness)

0x4 = Allow out-of-process component

0x40000 = Allow 32-bit component

0x80000 = Allow 64-bit component

0x100000000 = 2^32: Faster instantiation if component is guaranteed to instantiate quickly and reliably.

«user»

(optional text) the account name that the component will run under.

«password»

(optional text) the account password to obtain credentials for the «user» account.

In most cases, the instantiated object runs on the same machine as the Analytica calling process, however, remote invocation is possible, known as DCOM. When the «server» parameter is not specified, the target computer is determined by the DCOMCNFG settings for that component. By running the DCOMCNFG program, or entering "DCOM Config" in the Microsoft Component Services, you can configure specific COM components to run on specific remote servers. The «server» parameter overrides that setting. The COM component will usually need to be installed on both machines.

The programs that implement COM objects can either run in-process or out-of-process and can be 32-bit or 64-bit programs. Some COM servers provide both in-process and out-of-process versions and some provide both 32-bit and 64-bit versions. If you don't specify any of the optional flags, it'll set them to allow any possible combination that it finds to run (allowing either 32- or 64-bit and in-process or out-of-process). You can use these flags to force a specific type to run. For example:

COMCreateObject has some overhead involved in ensuring that Analytica can continue processing windows events (including Ctrl+Break) if the object takes a long time to instantiate or hangs. Adding the 2^32 bit to «flags» turns off this overhead, but it will appear that Analytica is hanging while waiting for it to instantiate, and you cannot interrupt it. You should only use this if you need very fast instantiation and can guarantee that your component does instantiate quickly and reliably.

COMCreateObject("MyObject", flags:0x1 + 0x80000)

would force the creation of a MyObject in an out-of-process 64-bit server, whereas without the flags it might have created an in-process 32-bit instance. Some COM servers provide only one type. For example, ABODB classes can only be used in-process.

Not all combinations of flags are valid. Here are some basic constraints:

• Any remote invocation (on a different machine) is automatically out-of-process.
• Any in-process invocation must have the same bitness (32-bit or 64-bit) as the Analytica or ADE program you are using. (Out-of-process bitness can differ).
• 64-bit objects can only be used when you are running Windows 64-bit.
• When neither «force64bit» nor «force32bit» are specified, it defaults to the same bitness as the calling process when both are available.

Using the .NET libraries

You can use these COM integration features to instantiate and use .NET objects, including certain .NET libraries (subject to security considerations).

Security

TBD. The user should be given control over whether COM objects are allowed to run, so that if you receive a model from someone else, it can't inflict arbitrary damage. Also, there should be restrictions on the ACP server as to what objects are allowed to run, and who can configure this.

Run as impersonation

It is possible to run out-of-process COM objects under a different identity. This can be configured in DCOMCNFG, or you can specify the «user» and «password» parameters.

Error handling

When you try to instantiate a COM object, it may fail with an error that terminates computation. There are situations where you don't want to terminate, but you might instead fall back on some non-COM-based algorithm instead. To do this, you can catch the error using the Try function:

Try( 
    COMCreateObject("MySearchComponent"),
Catch:
    Null
)

Ctrl+Break

While Analytica is instantiating the object, you can cancel the operation by pressing Ctrl+break, unless you have specified the fast instantiation bit (2^32) in the «flags» parameter to COMCreateObject. When you set that bit, the overhead for setting of a thread to handle windows events is avoided, but as a result if the operation takes a long time, Analytica will appear to hang while the instantiation is occurring and cannot be revived until the instantiation completes or times out.

COMCallMethod(object, methodName, param1, param2, param3,...,resultIndex: I, J,..., concurrent)

This calls a method of a COM object that has already been instantiated using COMCreateObject (or SpreadsheetOpen). The return value is the value returned by the method.

Methods can only be invoked for «object»s that implement the IDispatch interface.

Example:

Var ade := COMCreateObject("ADE4.CAEngine");

COMCallMethod(ade, "SendCommand","news");

COMCallMethod(ade, "OutputBuffer")

In the above example, the SendCommand method is invoked with the parameter "news". Its return value is ignored. Then the OutputBuffer property is accessed, and its value is returned.

Array-valued results

When a method returns an array (known as a SafeArray in COM lingo), the dimensions of that array need to be mapped to Analytica indexes. If you do not specify the «resultIndex» parameter, the function creates local indexes with the names .dim1, .dim2, etc. Alternatively, you can specify the indexes to use for the result via the «resultIndex» parameter. If your result index does not match the length of the corresponding dimension of the array that is returned, the array is truncated (when your index is too short) or result is padded with Nulls (if your index is too long). If you specify too many indexes (i.e., you provide 3 indexes but the result is only 2-D), the extra indexes are ignored. If you don't specify enough indexes, then local indexes are created as before.

Example:

COMCallMethod(reuters, "GetPriceHistory", "AAPL", 1-Jan-2012, Today(), resultIndex: Time, DateOpenCloseHighLow)

This hypothetical call returns the stock price history for a given stock from a start date to an end-date, where the result is a 2-D array. The first dimension of the result has one row for each date, and the columns are ['Date', 'Open', 'High', 'Low', 'Close']. The «resultIndex» parameter here maps these to existing Analytica indexes (named Time and DateOpenCloseHighLow).

Array-valued parameters

When you pass Analytica arrays as parameters, the call is iterated (invoked multiple times) for each atomic combination of parameters, and the results from each call are collected. Also, if the «object» parameter is array valued (an array of objects), the call is iterated, calling the method for each object. Hence, array-abstraction extends to COM method calls.

When a method expects an array-valued parameter, you must package it using the COMArray function, which specifies which indexes are consumed along with the order of the indexes for 2-D or greater arrays. Any indexes that are not included within the COMArray call are iterated over.

Examples

COMCallMethod(mathObj, "PrincipleEigenVector", COMArray(A, I, J), resultIndex: I)

This hypothetical method accepts a 2-D matrix and returns a 1-D vector.

COMCallMethod(reuters, "OpenPriceOnGivenDates", Stock, COMArray(Time, Time), resultIndex: Time)

This hypothetical method accepts a stock symbol and a 1-D array of dates. It returns a vector containing the stock price on each date. The model may send this an array of stock symbols. The array will be called once for each stock, and the results collected in an array having all the dimensions of Stock.

Pass-by value

All parameters are passed-by-value. The option to pass-by-reference is not available. This limits the methods that can be called to those without pass-by-reference parameters (a.k.a., "out" parameters).

Data types

Parameters are passed as COM VARIANTs. COM Objects themselves can be passed as parameters and result values can return COM objects. Hence, it is possible to have methods that return a new COM object, and then that object can be used as the first parameter in a call to COMCallMethod, COMGetProperty, obj->property, etc.

The Invoke Method operator

A new -> operator provides a syntactic convenience for COMCallMethod. The use of the operator looks like this:

obj -> method(param1, param2,..)

Names parameters

The COM Automation specification has a concept of named parameters. This is not supported by COMCallMethod. Parameters are passed by position only.

Error handling

Errors in the COM layer cause an error message to appear and evaluation to terminate.

COM objects may themselves implement error handling in various ways, such as by including an ErrorCode property that the caller can check after a method call, etc. These are just return values and are not interpreted as errors by Analytica.

Concurrent calls

When you specify the optional «concurrent» as true, COMCallMethod returns right away, and returns a special COM object that encapsulates the state of the computation. Your model can then work on something else, or launch other concurrent calls. Your model will need to eventually ask the object for the result, or it can query the object to find out it the call has finished yet.

The special object returned supports these properties and methods:

• (property, read-only) IsDone
• (property, read-only) HasError
• (method) Result() { Blocks until done, issues an error if there was an error }

This example creates three parallel computations, one for each molecule. Two of the molecule folds are computed on this computer, and one is computed on a remote computer named Computer2. A lengthy CalculateFold method is called, and the three computations run in parallel. The final line waits for them all to complete and merges the results into a single array. The local variable, h, holds the special COM object that tracks the state of the concurrent computations.

Index molecule := ["JunK", "JanA", "TcpK"];

Var computer := Array(molecule, ["LocalHost", "LocalHost", "Computer2"]);

Var obj := COMCreateObject("ProteinFolder", server: computer);

Var h := COMCallMethod(obj, "CalculateFold", molecule, concurrent: true);

COMCallMethod(h, "Result")

Once the concurrent COMCallMethod evaluates, thus starting the concurrent computations, the computations continue in the client components even if you abort the computation in Analytica (via Ctrl+break or because of an error). If the concurrency object returned from COMCallMethod is cached, you can evaluate the Result() method later and get the result.

Overloaded methods

The .NET libraries allow functions to be overloaded. For example, in the System.Random class, there are three overloads for the method Next:

int Next();

int Next(int);

int Next(int, int);

Even though COM doesn't support method overloading, COMCallMethod will find the matching .NET overloads and call it. When .NET wraps an class in a COM wrapper, it adds overloaded variants of methods by appending an underscore and number, starting with 2, to create new names for the overloaded variants. It the example of Next, it exposes three methods

int Next();

int Next_2(int, int)

int Next_3(int)

As an illustration, the following uses the .NET class System.Random to generate an integer between 200 and 300:

Var sysRand := COMCreateObject("System.Random") Do sysRand- > Next_2(200, 300)

However, you don't need to figure out the overloaded name. If you simply use

Var sysRand := COMCreateObject("System.Random") Do sysRand -> Next(200, 300)

COMCallMethod will first call Next(), and with that fails (with an invalid number of parameters error), it will then look for a Next_2 variant, then a Next_3 variant, and so on, until it eventually finds the appropriate variant. However, overloading resolution does not occur when the «concurrent» flag is true.

COMPutProperty(object, propertyName, value, params: param1, param2, param3,...)

Sets a property of a COM object to «value».

Most properties are simple properties, so that COMPutProperty is akin to an assignment. In these cases, the «params» parameters are not used. In less common cases, a COM object may have an indexed property that accepts parameters, similar to array coordinates for the property (although they need not be array coordinates), and these indexed parameters are specified in «params».

COMPutProperty calls IDispatch::Invoke with the DISPATCH_PROPERTYPUT flag. No method for calling with DISPATCH_PROPERTYPUTREF will be provided.

No return value. In other respects, same as COMCallMethod.

Syntactic shortcuts:

obj->propertyName := value

obj->propertyName(param1, param2) := value

COMGetProperty(object, propertyName, param1, param2, param3,..., resultIndex: I, J,...)

Returns the value of a property. This is the same as COMCallMethod, except that it is invoked with the DISPATCH_PROPERTYGET flag. The following syntactic shortcut can be used for an non-indexed, scalar-valued property:

obj -> propertyName

If parameters need to be passed, then you must call the function explicitly.

TypeOf

You can test whether a scalar value holds a COM object using TypeOf in TypeOf(X, true) = "COM Object".

Limitations

The Analytica-COM integration facility comes with several notable limitations.

• Objects must support the IDispatch interface (this is known as ActiveX automation). All calls and property accesses are automation calls. Native COM calls are not supported.
• Methods calls with reference parameters are not supported. Calls have a single return value only.
• Expression Assist cannot "see" the names of the properties and methods supported by an object, so it can't assist you with possible method-name completions while typing. Also, non-existent method errors (from bad names) aren't detected until evaluation time.

Application examples

• Distributed Computation using ADE
• Working with Excel Worksheets using the Excel 2013 Object Model.
• Writing your own COM component using VB.NET
• Writing your own COM component using VC++
• Parsing an XML file example model.

History

Introduced in Analytica 4.6.

See Also

• COM Automation Objects
• Configuring DCOM for remote invocation
• Excel Functions from ADE