Using the Analytica Decision Engine Server

ADE User Guide > Using the Analytica Decision Engine Server

This chapter describes the Analytica Decision Engine server classes CAEngine, CALicense, CAObject, CATable, CAIndex, and CARenderingStyle, and the server class architecture.

ADE Classes

ADE uses the following six classes:

• The CAEngine class contains methods and properties that allow you to open and close existing models, create new models, create new Analytica objects, and access Analytica objects contained in your model.
• The CALicense class contains methods that allow you to instantiate a CAEngine, to use a special application license code, to examine certain restrictions on your ADE license, and to access details about why a CAEngine failed to instantiate.
• The CAObject class contains methods and properties that allow you to set and obtain information about the Analytica objects (such as variables or modules) that you obtain from the CAEngine class.
• The CATable class is used to examine multi-dimensional results or to view and modify multidimensional definition tables (also called edit tables).
• A CAIndex object provides access to one dimension of a multi-dimensional CATable.
• The CARenderingStyle class is new in ADE 4.0, and allows you to control or alter the format in which ADE returns values.

Note: “CA” in these class names stands for “Class Analytica.”

The following sections describe how to access these Analytica Server objects from Visual Basic or C#.

Server Class Architectures

COM, Autoation, and .NET

ADE 4.6 supports two calling conventions: COM and ActiveX Automation. COM is an early-binding convention in which the methods and data types are resolved when your application code is compiled. Automation is a late-binding convention where method calls are resolved at run time. The COM convention is somewhat more efficient, although for most applications, the difference in efficiency is far overshadowed by the time required to compute your model’s results.

In Visual Basic, the syntax for calling a method using COM or Automation is identical, and which interface is used depends on how you declare your objects. In other languages, such as C# or C++, the method of invocation can look quite different. In C# and C++, it is generally more convenient to use the COM interface. VBScript (used by the Windows Scripting Host and older versions of IIS ASP) supports only the Automation interface.

The COM interface can be used transparently from a .NET environment such as Visual Studio 2005. The .NET programming environment wraps COM objects with a .NET Interop object, which gives ADE interfaces the appearance of being .NET interfaces.

In ADE 3.1 and before, the Automation interface was the recommended convention; however, with the ADE 4.6 release, we now recommend the COM interface unless this is not an option in your programming environment (such as VBScript).

In-process vs Out-of-process

ADE can be launched either in-process or out-of-process. When launched in-process (ADEW), the Adew.dll library is loaded into your application’s process space. When launched out-of-process (ADE), the ADE.exe server is launched and runs in a different process. Both types of server use the same class interfaces, so the choice of which type of server to use can usually be changed by editing a single line of code, i.e., the line that instantiates the CAEngine.

In-process servers have a slight performance advantage, but come with several restrictions. First, the apartment threading model of ADEW must be compatible with your application’s threading model. For example, The Microsoft IIS web server (IIS 5.0 or later) does not allow you to use an apartment-threaded component under its default settings. Also, you are restricted to have only one CAEngine instance (and thus, only one model) in memory at any one time.

Out-of-process instances of ADE run in a different process, and can be configured to run on a different computer from your application. Because data must be “marshaled” across process boundaries, it is less efficient, but it is far more flexible than the in-process server. Your program can make use of multiple simultaneous instances of ADE, each with a separate model instance loaded. As such, the out-of-process server is almost always preferred for web applications because you can have one ADE instance for each session

Typescript

In addition to the program interface, ADE has a fully functional command interface, known as the typescript language. This language is described in the Analytica Scripting Guide. This language allows access to all of ADE’s functionality. The API provides a more convenient, object-oriented set of functions for communication with the engine from Visual Basic and C++ applications. A calling program can use the API functions, or it can pass typescript commands directly to the typescript interface.

Security Permissios under IIS

When creating a web application that uses ADE from within Microsoft’s Active Server Pages (ASP/ASPX) under Internet Information Server (IIS), you might need to configure permission settings in order to instantiate and access the ADE COM component from your program.

When creating a web application or web service, you should use the out-of-process ADE server. When your ASPX application is executed while serving a web page request, the ADE COM component is launched and accessed from a special internal Windows account name. Even though your programs can create and access ADE when run under your account, the same access might not exist for ASP or ASPX programs. To configure security permissions so that your ASPX application can use ADE, follows these steps:

1. From the Windows Control Panel, select Administrative Tools > Component Services.
   • Note: If you are using ADE 32-bit on a Windows 64-bit machine, then you must instead run: mmc comexp.msc /32
2. In the DCOM Config folder, locate “Analytica Decision Engine Local Server 4.6.”
3. Select Properties from the right mouse menu, and select the Security tab.
4. Set Launch and Activation Permissions to Customize, then click Edit.
5. Grant local launch and local activation permissions for the account used by IIS. In IIS 5 this is usually {computer_name}\ASPNET. In IIS 6 & 7 this is usually NETWORKSERVICES or IIS_IUSRS. In IIS 7.5, these should be set for the Application Pool name, which is usually “IIS AppPool\DefaultAppPool”.
6. Save these settings. You might need to reboot of the machine to finalize these changes. When these permissions are not properly configured, a “security exception” occurs on the line of your program that attempts to instantiate the CAEngine