COM Automation Objects

Analytica User GuideIntegration with data and applicationsCOM Automation Objects

The Microsoft Component Object Model (COM) provides a framework for interprocess communication within the Windows operating system. Using the functions described in this section, you can instantiate and call other applications that expose a COM automation interface (known as the IDispatch interface). You can write your own COM servers in C++, C#, VB, and a host of other languages, and then call them, or you can use existing interfaces to call applications from other vendors.

These functions allow your model to call other applications. This is different from having other applications call your Analytica model. The Analytica Decision Engine (ADE) product provides the latter functionality.

This feature is available in Analytica Enterprise and Optimizer.

If you intend to use these functions, you should refer to COM Integration, where the topic is covered in greater depth.

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

Instantiates a COM object. This is the first step when using COM. Only the first parameter, «name», is required, which is the textual name of a registered server such as "ADE6.CAEngine", "MSXML2.DomDocument" or "clsid:72C24DD5-D70A-438B-8A42-98424B88AFB8".

The optional «server» parameter is the name of the computer where the object will be run for remote invocation. Without this parameter, the object is instantiated on the same computer where Analytica is running.

The «flags» parameter allows control over several esoteric flags. These may be added together. The most notable flags are:

• 0x1 = Allow in-process instantiation
• 0x2 = Allow out-of-process instantiation
• 0x40000 = Allow 32-bit component
• 0x80000 = Allow 64-bit component
  

To specify the account credentials that the object will run under, you may specify the «user» and «password» parameters.

You will usually set aside a variable as the object that is instantiated. The definition to this variable will be just a call to COMCreateObject(). The object itself will persist (i.e., continue running) as long as the variable remains computed. When the variable is invalidated, the object is released and the COM server will usually terminate. If you hold the result of COMCreateObject() in a local variable, the COM object is released when the local variable falls out of scope (more generally, when Analytica the last use of the object falls out of scope).

obj -> method()

After using the COMCreateObject() or SpreadsheetOpen() function to instantiate an automation object, you can call method or read and write properties of the object using the -> operator, as show in this example which calls a method:

ade -> OpenModel("Portfolio.ana”)

where Variable ade is defined as COMCreateObject("ADE6.CAEngine"). Without parenthesis, properties are read, e.g.,

ade -> OutputBuffer

and properties can be set using assignment,

ade -> DefaultRenderingStyle -> StringQuotes := 2

The → operator provides a convenient and terse syntax resembling the object syntax of many programming languages, but you should think of this operator as being an abbreviation for the COMCallMethod(), COMGetProperty() and COMPutProperty() functions. Each of these functions provide additional options that are useful in some circumstances.

COMCallMethod(obj, methodName, parameters..., resultIndex..., concurrent)

Calls the method of «obj» named «methodName», passing zero or more «parameters» to the method. When the method returns an array, you may want to map this to existing indexes in your model, which is done by specifying the result index or indexes in the «resultIndex» parameter. Because «parameters» may have any number of specified arguments, «resultIndex» must be specified using the named parameter calling syntax. The optional «concurrent» parameter issues method calls asynchronously or in parallel.

Example:

The GetPriceHistory method of the Reuters object returns a 2-D array of historic stock prices (this is a hypothetical app sold by a hypothetical 3rd party). The first dimension is the trading date, the second has for items: the Open, Close, High and Low. The method itself accepts three parameters: a stock symbol, a start and and end date. You wish to map the result to indexes that already exist in your model.

COMCallMethod(reuters, ”GetPriceHistory”, ”AAPL”, 8-Jan-2014, Today(), resultIndex:Time, DateOpenCloseHighLow)

COMArray(x, i...)

When you pass Analytica arrays as parameters of a COM method, the call is iterated (invoked multiple times) for each atomic combination of parameters, and the results from each call are collected. When a method expects an array-valued parameter, you must package it using the COMArray function. The first parameter, «x», in the array being passed, and the remaining parameters are the Analytica indexes of «x». The list of indexes tells it which indexes are intrinsic (any not listed are iterated) and the order of dimensions that the server expects.

Example:

mathObj -> PrincipleEigenVector(COMArray(X, I, J), resultIndex: I)

The method called here expects a 2-D matrix and returns a 1-D vector.

COMGetProperty(obj, propertyName, parameters..., resultIndex...)

Retrieves a property with the given name. Most properties have no parameters, so usually this call is used with only obj and «propertyName», and even more commonly the syntax obj -> propertyName is used instead. Some COM objects have indexed properties (the parameters usually act like subscripts), and in those cases «parameters» may be specified. To call an indexed property, you must use COMGetProperty(), since the obj -> name(x) syntax where the name is followed by parenthesis for a parameter list is interpreted as a method call. Some COM applications make a strong distinction between methods and properties, others don’t.

When COMGetProperty is called, «propertyName» is text, surrounded by quotes, or an expression that evaluates to text. The «resultIndex» specifies the Analytica indexes for the result when the property’s value is an array.

Example:

COMGetProperty(Wnetwork, "UserDomain")

Which is equivalent to

Wnetwork -> UserDomain

COMPutProperty(obj, propertyName, value, parameters...)

Sets the property named «propertyName» of «obj» to «value». The call

COMSetProperty(renderStyle, ”NumberAsText”, true)

is equivalent to

renderStyle -> NumberAsText := true

When a property is an indexed property, «parameters» are specified, usually indicating subscript coordinates of some kind. See COMPutProperty().

See Also

• Attrib of Obj
• COMArray()
• COMCallMethod()
• COMCreateObject()
• COMGetProperty()
• COMPutProperty()
• COM Integration
• Configuring DCOM for remote invocation

Accessing a multidimensional or OLAP database with MDXCOM Automation ObjectsRunConsoleProcess - call other applications