View source for Using the Analytica Decision Engine Server

[[Category:ADE User Guide]]
[[ADE User Guide|<< Back to 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, 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 <tt>Adew.dll</tt> library is loaded into your application’s process space. When launched out-of-process (ADE), the <tt>ADE.exe</tt> 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.

[[File:AnalyticaDecisionEngineArchitecture.jpg]]

===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: 

#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:'' <tt>mmc comexp.msc /32 </tt>
#In the '''DCOM Config''' folder, locate “Analytica Decision Engine Local Server 4.6.” 
#Select '''Properties''' from the right mouse menu, and select the Security tab. 
#Set '''Launch and Activation Permissions''' to '''Customize''', then click '''Edit'''.
#Grant local launch and local activation permissions for the account used by IIS. In IIS 5 this is usually <tt>{computer_name}\ASPNET</tt>. In IIS 6 & 7 this is usually <tt>NETWORKSERVICES</tt> or <tt>IIS_IUSRS</tt>. In IIS 7.5, these should be set for the Application Pool name, which is usually “<tt>IIS AppPool\DefaultAppPool</tt>”.
#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 <tt>AdeTest.exe</tt>. The executable can be found in the <tt>Examples/AdeTest/bin directory</tt>. You can use AdeTest to exercise the functionality of either the in-process (<tt>Adew.dll</tt>) or the local process (<tt>ADE.exe</tt>) 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 (<tt>Adew.dll</tt>) instance, while the second two are out-of-process local servers (<tt>ADE.exe</tt>) 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.

[[File:ADETestDialog.jpg]]

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: <tt>

:ADE.Photo=True
:ADE.Photo=False </tt>

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

==Sample application in Excel's Visual Basic==
Another example program called <tt>excel_exam</tt> is also included in the ADE package. The program, <tt>Analytica.xls</tt>, in the <tt>excel_exam</tt> 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 <tt>asp_exam</tt> 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 <tt>readme.txt</tt> 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 (<tt>ADE.exe</tt>), you can ensure that each web application, or even each session, uses a different version of <tt>ADE.exe</tt>. 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 2005===
From a Visual Basic, C#, J#, ASP.NET, or C++/CLR project in Visual Studio 2005, 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 2005, 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: <tt>
:Analytica Decision Engine Local Server 4.6 
:Analytica Decision Engine Server 4.6 </tt>

For out-of-process <tt>ADE.exe</tt> servers, select the Local server. To use <tt>Adew.dll</tt>, 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 <tt>using</tt> declaration to the top of your source files, like this: <tt>
:Imports ADE ’ Visual basic 
:using ADE; // C# 
:using namespace ADE; // C++/CLR 
:import ADE.*; // J#</tt>

Of course, when using the in-process server you would type <tt>ADEW</tt> in place of <tt>ADE</tt> 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: <tt>
:dim ADE as [[CAEngine]] = new CAEngineClass ’ VB
:[[CAEngine]] ADE = new CAEngineClass(); // C#, J# 
:[[CAEngine]]^ pAde = gcnew CAEngineClass();   // C++/CLR </tt>

[[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):<tt>
:System.Runtime.InteropServices.Marshal.ReleaseComObject(ADE); 
:ADE = null; </tt>

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 <tt>ADE.exe</tt> 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: <tt>
:System.GC.Collect()</tt>

===From an ATL Project in C++===
To use ADE 4.6 from a non-.NET C++ project, place the following two lines at the top of your source file: <tt>
:<nowiki>#</nowiki>import "ADE.exe" 
:using namespace ADE; </tt>

Or to use the in-process server, use these lines: <tt>
:<nowiki>#</nowiki>import "Adew.dll" 
using namespace ADEW; </tt>

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

Next, obtain the first instance to an ADE engine using this code:<tt>
:CoInitialize(NULL); 
:CAEnginePtr pAde(__uuidof(_CAEngine)); 
:. 
:. 
:. 
:CoUninitialize(); </tt>

'''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 <tt>stdafx.h</tt>): <tt>
:<nowiki>#</nowiki>import "ADE.exe" no_implementation </tt>

And then in one file only (e.g., stdafx.cpp), include this line: 
:<nowiki>#</nowiki>import "ADE.exe" implementation_only</tt>

==Using the ADE Automation Interface==
VBScript is an example of a scripting language, usable from Windows Scripting Host (<tt>CScript.exe</tt> or <tt>WScript.exe</tt>), 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 in ADE 4.6. 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: <tt>
:dim ADE as Object 
:ADE = CreateObject("ADE4.CAEngine") </tt>

In VBScript, and some older versions of Visual Basic, the set keyword is required: <tt>
:dim ADE 
:set ADE = CreateObject("ADE4.CAEngine") </tt>

For the in-process server, you send the parameter '''ADEW4.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.
#Use the '''Send''' method to send the command to the Engine. If the '''Send''' method returns <tt>True</tt>, then the command was processed without error by ADE.
#Store the error code and error text (if the return code is nonzero). These two pieces of information are stored in the [[CAEngine]] properties '''ErrorCode''' and '''ErrorText'''.
#Get the output by calling the '''OutputBuffer''' function in the [[CAEngine]] class. 

'''''Note:''' You can also combine the first two steps by calling <tt>CAEngine.SendCommand(cmd)</tt>.'' 

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=== 
<tt>
: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 </tt>

===In VBScript=== 
<tt>
:set ADE = CreateObject("ADE4.CAEngine") 
:ADE.Command = “news” 
:If ADE.Send = False Then 
::ErrCode = ADE.ErrorCode 
::ErrT = ADE.ErrorText 
:Else 
::Result = ADE.OutputBuffer 
:End if </tt>

===In C#=== 
<tt>
: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; 
::::}
:::}
::}
:}</tt>

===In J#=== 
<tt>
: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(); 
:::} 
::} 
:} </tt>

===In C++/CLR===
<tt>
: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; 
::} 
:} </tt>

===In VC++ (without .NET)===
<tt>
:<nowiki>#</nowiki>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();
:}</tt>

==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==
{| style="margin: 1em auto 1em auto;width: 100%;border:0;table-layout: fixed;" cellpadding=5
|+ ADE User Guide Navigation
|- style="text-align: center"
|  [[The Analytica Decision Engine Tutorial]] << Previous  ||  [[Using the Analytica Decision Engine Server]] || Next >> [[Working with Models, Modules, and Files in ADE]]
|}