使用ADE服务器

ADE 用户指南 >

此章描述了Analytica决策引擎服务器类型 CAEngine、 CALicense、 CAObject、 CATable、　CAIndex和 CARenderingStyle，以及服务器类型构架。

ADE 类型

ADE试用一下六种类型：

• 　CAEngine类型所包含的方法和属性允许你打开和关闭现有模型、建立新模型、建立新的Analytica对象，以及访问你模型中所包含的Analytica对象。
• CALicense类型所包含的方法允许你实例化　CAEngine、允许你使用一种特殊应用程序许可证代码、允许你检查ADE许可证上的某种限制、以及获取关于为什么　CAEngine未能成功实例化的详细信息。
• CAObject类型所包含的方法和属性允许你设置和获取从 CAEngine获取的Analytica 对象（例如变量模块）的相关信息。
• 　CATable类型用来检查多维结果或者查看和修改多维定义表格（也称为编辑表）。
• 一个CAIndex/CAIndex对象 允许你访问一个多维　CATable的一个维度。
• CARenderingStyle是在ADE 4.0中出现的新特征，允许你控制或改变ADE返回值的格式 。

注意： 着些类型名称中的“CA”代表“Class Analytica。”

下面的部分描述了如何从Visual Basic或者C#中访问这些Analytica Server对象。

服务器类型构架

COM、Autoation、 和.NET

ADE 4.6支持两种调用约定：COM和ActiveX Automation。COM是一种前期绑定的约定，在此约定中方法和数据类型会在你的应用程序代码被编译时确定。Automation是一种后期绑定的约定，在运行时间内决定方法调用。COM约定稍微有效一点，虽然对于大多数应用程序，该效率上的差异被计算模型结果所需时间远远地盖过。

在Visual Basic中，使用COM或Automation调用一种方法的语法是相同的，使用哪种结构取决于你如何声明你的对象。在其他语言中，例如C#或C++，调用方法看起来完全不同。在C#或C++中，使用COM结构一般更加方便。VBScript（Windows Scripting Host和更旧的IIS ASP版本使用）只支持Automation接口。

COM接口可以在.NET环境中，例如Visual Studio 2005，透明地使用。.NET编程环境通过使用.NET互操作对象隐藏了COM对象，这给与了ADE接口.NET接口的外观。

在ADE 3.1以及以前版本中，Automation接口是推荐使用的约定。但是随着ADE 4.6的发布，我们推荐使用COM接口，除非在你的编程环境（例如VBScript）中没法使用。

进程内和进程外比较

进程内服务器性能稍微好一点，但同时有一些限制。首先，ADEW的 单元 线程模型必须和你的应用程序的线程模型兼容。例如Microsoft IIS web server（IIS 5.0或后期版本）在其默认设置下不允许你使用单元-线程组件。其次，还限制你在任何时候在内存内只有一个 CAEngine实例（因此只有一个模型）。

ADE的进程外实例在不同进程内运行，能够设置让你从你的应用程序上在另一台电脑运行。因为数据必须是跨进程打包。你的程序可以同时使用多个ADE实例，每一个都有单独的载入模型实例。例如，过程外服务器几乎总是更适合web应用程序，因为对于每一个回话，你都可以有一个ADE实例。

Typescript

除了程序几口，ADE还有一个完整的函数命令结构，称为typescript语言。该语言在 Analytica Scripting Guide有描述。该语言允许你获取并使用ADE全部功能。API提供了一个更加方便、定向于对象的一组函数，用来从Visual Basic和C++中与引擎通讯。一个调用程序可以使用API函数，或者可以将typescript指令直接传递给typescript接口。

IIS下的安全性权限

当在Internet Information Server （IIS：互联网信息服务器）下的Microsoft Active Server Pages（ASP/ASPX：动态服务器页面）中使用ADE时，你可能需要陪着许可权限设置以便从你的应用程序实例化、访问ADE COM组件。

在建立一个web应用程序或者web服务器时，你应该使用进程外ADE服务器。当你的ASPX应用程序在提供页面请求时被执行的情况下，ADE COM 组件将从一个特殊的内部Windows账户名中启动并访问。即使在你的账户下运行时，你的应用程序能够建立并访问ADE，对于ASP或者ASPX来说不存在同样的访问。要配置安全性权限以便你的ASPX应用程序可以使用ADE，按照下面步骤操作：

1. 从Windows控制面板上选择管理员工具 > 组建服务.
   • 注意：如果你在一台64位计算机上使用32位版本ADE，那么你必须运行：mmc comexp.msc /32
2. 在DCOM Config 文件夹中找到“Analytica Decision Engine Local Server 4.6。”
3. 从右鼠标快捷菜单上选择Properties（属性） ，再选择 Security（安全性）标签。
4. 将Launch and Activation Permissions（启动并激活许可） 设置成Customize（自定义）然后点击Edit（编辑）
5. 授予IIS使用账户本地启动以及本地激活许可。在 IIS 5通常是{computer_name}\ASPNET。在IIS 6 & 7通常为NETWORKSERVICES或者 IIS_IUSRS，在 IIS 7.5，应该设置应用程序池名称上相应的这些设置。，通常为“IIS AppPool\DefaultAppPool”。
6. 保存这些设置。你可能需要重启你的机器才能完成这些改变。

当这些许可配置不正确时，在你尝试实例化的 CAEngine的程序上将出现一条“security exception” （安全故障）信息。

ADE测试程序

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

Analytica Decision Engine Local Server 4.6

Analytica Decision Engine Server 4.6

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

dim ADE as Object

ADE = CreateObject("ADE4.CAEngine")

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

dim ADE

set ADE = CreateObject("ADE4.CAEngine")

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.

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("ADE4.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