Using the ADE Server

ADE User Guide >

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, Automation, and .NET

ADE 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. 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 and later, 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 Permissions 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 6.4.”
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 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. 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 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. 

Using the ADE COM interface

From a .NET project in Visual Studio

From a Visual Basic, C#, J#, ASP.NET, or C++/CLR project in Visual Studio, you gain access to ADE by adding a reference to it in your project. The same technique holds with slight variations in older (pre-.NET) versions of Visual Basic and several other non-Microsoft development environments.

In Visual Studio, select Add reference or References from the Project menu, and in the dialog that appears, select the COM tab (in VC++ you need to click the Add new reference button to get to the COM tab). In the list of components, locate and select one of the following:

Analytica Decision Engine Local Server 6.4

Analytica Decision Engine Server 6.4

For out-of-process ADE.exe servers, select the Local server. To use Adew.dll, select the (nonlocal) server. It is also possible to add both references into a project (the AdeTest example does this), although the need for this would be rare.

The ADE classes are exposed in the name space ADE or ADEW for the local server and in-process server, respectively. For convenience, you can add a using declaration to the top of your source files, like this:

Imports ADE ’ Visual basic

using ADE; // C#

using namespace ADE; // C++/CLR

import ADE.*; // J#

Of course, when using the in-process server you would type ADEW in place of ADE above. These declarations allow you to refer to CAEngine, CAObject, etc., in your code, rather than ADE.CAEngine, ADE.CAObject, etc., which makes it easy to convert from the local to the in-process ADE server should the need arise.

To begin using ADE, you need to obtain a first instantiation of CAEngine. This is done with one of the following lines:

dim ADE as CAEngine = new CAEngineClass ’ VB

CAEngine ADE = new CAEngineClass(); // C#, J#

CAEngine^ pAde = gcnew CAEngineClass(); // C++/CLR

CAEngine is the name of a particular abstract interface, while ADEW.CAEngineClass and ADE.CAEngineClass are the names of two particular object classes that implement that interface. The CAEngineClass object is the only object that you can create directly; all other ADE object instances are obtained by calling methods on existing objects.

To keep the use of the COM interface, always declare your variables with the class names CAEngine, CAObject, CATable, CAIndex, and CARenderingStyle. Avoid assigning object instances to variables declared as System.Object. This allows the compiler to perform early binding and type checking.

Releasing objects in .NET

In pre-.NET Visual Basic and scripting languages, the programming environment automatically ensures that COM objects are released immediately. This is not the case in VB.NET, ASP.NET, or other .NET programs. From .NET, it is important that your program explicitly releases each COM object when it is through with it. Setting a pointer to Null (or Nothing) is not sufficient, since the actual release doesn’t occur until the next garbage collection.

To release a COM object from a .NET program, you need to execute code similar to the following (C# syntax shown):

System.Runtime.InteropServices.Marshal.ReleaseComObject(ADE);

ADE = null;

Releasing objects in this fashion is especially important when you are using an out-of-process COM server (e.g., ADE.CAEngine). In this case, the memory resources are predominantly consumed in the ADE process, not in your program’s process. This can cause the ADE process to run out of memory before your program’s process uses enough memory to cause an automatic garbage collection to occur. From a .NET-based web application, old ADE.exe processes linger long after a session has finished unless you explicitly release the CAEngine object.

This need to release COM objects is not unique to ADE. You must take care to release any COM object, including those provided by Microsoft, especially when those COM objects are out-of-process.

Because of this absence of deterministic destruction in .NET, it can be tedious to ensure that every COM object is released. Therefore, you might want to occasionally force an explicit garbage collection in your code, which releases all unused objects. This can be accomplished by calling:

System.GC.Collect()

From an ATL Project in C++

To use ADE from a non-.NET C++ project, place the following two lines at the top of your source file:

#import "ADE.exe"

using namespace ADE;

Or to use the in-process server, use these lines:

#import "Adew.dll"

using namespace ADEW;

You need to include the ADE home directory in your include path in the project settings, or spell out the complete path in the #import declaration.

Next, obtain the first instance to an ADE engine using this code:

CoInitialize(NULL);

CAEnginePtr pAde(__uuidof(_CAEngine));

.

.

.

CoUninitialize();

CoInitialize() is a Windows system call that is required before the COM system can be used.

If your project spans multiple code files, use this in each of your source files (or once in stdafx.h):

#import "ADE.exe" no_implementation

And then in one file only (e.g., stdafx.cpp), include this line:

#import "ADE.exe" implementation_only

Using the ADE Automation Interface

VBScript is an example of a scripting language, usable from Windows Scripting Host (CScript.exe or WScript.exe), pre-.NET versions of Active Server Pages, Internet Explorer, and so on. JScript is another, and many other scripting OLE-Automation compliant scripting languages are available including Perl.

These scripting languages support ActiveX Automation scripting, but not COM interfaces. Using the Automation interface, ADE can be used from these, often with no additional tools beyond a simple text editor.

For ADE releases prior to 4.6, the Automation interface was the preferred convention to use. For languages that support direct COM calls, the COM convention is now recommended. Using Automation from C++ or C# is rather tedious and not covered here.

From Visual Basic or VBScript

To use the Automation interface, it is not necessary to add a reference to your Visual Basic project. The syntax here is similar in other scripting languages. In Visual Basic, the code to instantiate a CAEngine is:

dim ADE as Object

ADE = CreateObject("ADE6.CAEngine")

In VBScript, and some older versions of Visual Basic, the set keyword is required:

dim ADE

set ADE = CreateObject("ADE6.CAEngine")

For the in-process server, you send the parameter ADEW6.CAEngine to the CreateObject call.

ADE Typescript: Command Language Communication

The Command property and Send method of the CAEngine class allow you to use typescript commands, sent as ASCII strings to the engine, and receive the resulting output as another ASCII string. You might want to use a typescript command instead of an API method if:

• You want to perform your own parsing on ADE output (e.g., on tabular data that are output from the Analytica Decision Engine as text strings of comma-delimited text).
• No appropriate API method exists.

You perform these steps to send a typescript command to ADE: !Assign a text string containing the command to the Command property of your CAEngine object.

1. Use the Send method to send the command to the Engine. If the Send method returns True, then the command was processed without error by ADE.
2. Store the error code and error text (if the return code is nonzero). These two pieces of information are stored in the CAEngine properties CAEngine::ErrorCode and ErrorText.
3. Get the output by calling the OutputBuffer function in the CAEngine class.

Note: You can also combine the first two steps by calling CAEngine.SendCommand(cmd).

These steps are demonstrated below for various programming languages. After these simple examples, subsequent examples are given using a Visual Basic syntax, but you should have no problem extrapolating the syntax to your language of choice.

In Visual Basic

Imports ADE

Module Module1

Sub Main()

Dim Result,ErrT As String

Dim ErrCode as Integer

dim ADE as CAEngine = new CAEngineClass

ADE.Command = "news" ’any typescript command

dim SendCode as Boolean = ADE.Send

If SendCode = False Then

ErrCode = ADE.ErrorCode

ErrT = ADE.ErrorText

Else

Result = ADE.OutputBuffer

End If

End Sub

End Module

In VBScript

set ADE = CreateObject("ADE6.CAEngine")

ADE.Command = “news”

If ADE.Send = False Then

ErrCode = ADE.ErrorCode

ErrT = ADE.[[CAEngine::ErrorText|ErrorText\\

Else

Result = ADE.OutputBuffer

End if

In C#

using System;

using ADE;

namespace ADE_from_Csharp

{

class Program

{

static void Main()

{

String errT, result;

int errCode;

CAEngine ADE = new CAEngineClass();

ADE.Command = "News";

if (!ADE.Send()) {

errCode = ADE.ErrorCode;

errT = ADE.ErrorText;

} else {

result = ADE.OutputBuffer;

}

}

}

}

In J#

import ADE.*;

public class Program

{

public static void main( )

{

String errT, result;

int errCode;

ADE.CAEngine ADE = new ADE.CAEngineClass();

ADE.set_Command("News");

boolean sendRes = ADE.Send();

if (!sendRes) {

errCode = ADE.get_ErrorCode();

errT = ADE.get_ErrorText();

} else {

result = ADE.get_OutputBuffer();

}

}

}

In C++/CLR

using namespace System;

using namespace ADE;

void main( )

{

String ^result, ^errT;

int errCode;

CAEngine^ ADE = gcnew CAEngineClass();

ADE->Command = "News";

if (!ADE->Send()) {

errCode = ADE->ErrorCode;

errT = ADE->ErrorText;

} else {

result = ADE->OutputBuffer;

}

}

In VC++ (without .NET)

#import "ADE.exe"

using namespace ADE;

void main( )

{

CoInitialize(NULL);

_bstr_t errT, result;

int errCode;

_CAEnginePtr pAde(__uuidof(_CAEngine));

pAde->Command = "News";

if (!pAde->Send()) {

errT = pAde->ErrorText;

errCode = pAde->ErrorCode;

} else {

result = pAde->OutputBuffer;

}

CoUninitialize();

}

Errors and Error Handling

The CAEngine properties ErrorCode and ErrorText should be queried after any operation with ADE whenever an error is possible. Reading a value of a property from an ADE object does not change the error code. Setting the value of a property might result in an error, usually indicating an illegal value for that property. All method calls reset ErrorCode to zero if there is no error, or to a value indicating the error.

To get additional information on an error, check the OutputBuffer property of CAEngine. Any error messages that a user of Analytica would have seen appear in the output buffer.

See Also

The ADE Tutorial <-

Using the ADE Server

-> Working with Models, Modules, and Files in ADE