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.

The ADE Test Program

ADE 4.6 ships with a sample program called AdeTest.exe. The executable can be found in the Examples/AdeTest/bin directory. You can use AdeTest to exercise the functionality of either the in-process (Adew.dll) or the local process (ADE.exe) versions of ADE 4.6. Using AdeTest, you can send script commands to the engine, create ADE objects, and set or call virtually any of the properties and methods of the ADE objects. If you have Visual Studio 2005 installed, you can step through the code in the Visual Studio Debugger to observe the methods being called.

The image below shows the AdeTest program dialog. The left-hand pane shows a list of ADE objects that the program is currently holding. The right side shows details of one of those objects. In the figure, there are three CAEngine instances, each with a different model open. The first CAEngine is an inprocess (Adew.dll) instance, while the second two are out-of-process local servers (ADE.exe) instances. The two buttons above the left pane can be used to create additional CAEngine instances, while the Release button at the lower-right corner of the right-hand panel releases an instance. The right-hand panel shows information about the third CAEngine instance. The current values for the CAEngine properties ErrorCode, ErrorText, CurrentModule, OutputBuffer, and Photo are displayed. You can execute a typescript command by typing the command into the text box and clicking the Send button. Or you can execute any of the method of CAEngine by selecting the method in the drop-down Method box, filling in the parameters, and clicking the Execute Method button.

If you click an object in the left-hand pane, the properties for that object are displayed on the righthand side and you can set its properties or call its methods. Thus, you can simulate a series of steps your program might execute through the graphical interface.

When a method returns an object, for example, as with CAEngine::GetObjectByName, the returned object is added to the tree on the left as a child of the object that created it. After executing a method from a class other than CAEngine, it is a good idea to glance at the corresponding CAEngine’s panel to check the ErrorCode, ErrorText, and OutputBuffer properties.

The Photo checkbox in the Analytica window is mirrored by the Photo property of the CAEngine class. By default the Photo property is False, so typescript communications between the client and ADE are not copied to the Analytica log window. Setting the Photo property to True copies all subsequent typescript communications between the client and ADE. In Visual Basic, this would be done as follows:

ADE.Photo=True
ADE.Photo=False 

Turning on the Photo property significantly slows down communication with ADE.

Sample application in Excel's Visual Basic

Another example program called excel_exam is also included in the ADE package. The program, Analytica.xls, in the excel_exam directory can be loaded into Microsoft Excel and executed as a macro. This program demonstrates the use of Visual Basic for Applications in Excel for ADE communications. This sample makes use of the local server version of ADE.

Sample ASP web application

The example in asp_exam demonstrates the use of ADE from an Active Server Pages web application. This application produces a hierarchical outline of your model structure in HTML. The readme.txt file in that directory contains instructions for configuring the web server to run the example.

When using Microsoft’s ASP, we recommend that you use the local server. By using the local server (ADE.exe), you can ensure that each web application, or even each session, uses a different version of ADE.exe. Currently, there is a limitation in ADE that prevents creation of two or more in-process server objects at the same time. Therefore, if you expect to have more than one session of ADE active at one time (as is almost always the case in web-based applications), always use the local server of ADE.