Using the ADE Server/zh

ADE用户指南 >

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

ADE 类型

ADE使用一下六种类型：

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

进程内和进程外比较

ADE可以在进程内或进程外启动。当我们在进程内（ASEW）启动时，Adew.dll库被载入到你的应用程序进程空间内。当启动进程外（ADE）时，ADE.exe服务器启动，并且在不同进程内运行。两种服务器类型都是用相同的类型接口，所以到底选择使用哪种服务器通常可以通过编辑单独实例化CAEngine的这一行代码就可以改变选择。

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

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

Typescript

除了程序接口，ADE还有一个完整的函数命令结构，称为typescript语言。该语言在Analytica脚本指南有描述。该语言允许你获取并使用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测试程序

ADE 4.6和名称为AdeTest.exe的示例程序一同安装。可执行文件位于Examples/AdeTest/bin 目录。你可以使用AdeTest来联系内部进程（Adew.dll）或者AD4.6E的本地进程（ADE.exe）版本的功能。通过使用AdeTest，你可以将脚本指令发送给引擎，建立ADE对象，实际上设置或调用ADE对象的任何属性和方法。如果你安装了Visual Studio 2005，你可以逐句调试Visual Studio Debugger中的代码以观察调用的方法。

下面的图像显示了AdeTest程序对话窗口。左手边的窗体显示了一个当前程序所包含的ADE对象列表。右边显示了其中一个对象的详细信息。在此图中，有三个CAEngine实例，每一个都有一个打开的不同模型，第一个CAEngine是一个个进程内实例（Adew.dll</tt），而其他两个是进程外服务器实例（ADE.exe</tt）。当右手边窗体右下角的Release按钮释放一个实例时，左边窗体上方的两个按钮可以用来建立其他的CAEngine实例。右边窗体显示了第三个CAEngine实例的相关信息。CAEngine相关属性：ErrorCode、ErrorText、CurrentModule、OutputBuffer，和 Photo 的当前值将显示。通过将指令输入进文本框并点击Send （发送）按钮，你可以执行一个typescript指令。或者通过选择Method （方法）下拉框中的方法，填写参数并点击Execute Method（执行方法）按钮，你可以CAEngine的任何一种方法。

如果你点击右手边窗体中的一个对象，其对象属性将显示在收邮编，你可以设置其属性或者调用其方法。因此，你可以模拟你的程序在一个图形接口界面可能执行的一系列的步骤。

当一种方法返回一个对象时，例如，就'CAEngine::GetObjectByName来说，返回对象被添加到左手边的关系树上成为创建它的对象的子对象。在从一个类型而非CAEngine执行一种方法后，浏览一下相应的CAEngine面板检查ErrorCode、ErrorText，和OutputBuffer 等属性是一个不错的习惯。

Analytica窗口上的Photo复选框是CAEngine类型Photo 属性的映射。默认情况下Photo的属性是 False（假），因此用户和ADE之间的typescript通讯不会被复制到Analytica日志窗口中。将Photo属性设置成True（真）将复制用户和ADE之间的所有后继的typescript通讯。在Visual Basic中，实现此过程如下所示：

ADE.Photo=True

ADE.Photo=False

打开Photo属性将明显减慢与ADE之间的通讯。

Excel中Visual Basic样本应用程序

另一个名称为excel_exam的示例应用程序也包含到ADE程序包中。在excel_exam目录下的 Analytica.xls程序可以载入到Microsoft Excel中，作为一个宏来运行。该程序演示了Visual Basic如何用来在Excel中应用程序里面和ADE通讯。该示例使用了ADE本地服务器版本。

ASP web 应用程序示例

asp_exam中的示例演示了如何从一个动态服务器页面web应用程序中使用ADE。该应用程序生成了一个使用HTML语言编写的你的模型结构的分层大纲。该目录中的readme.txt文件包含配置运行该示例的web服务器的说明。

在使用Microsoft的ASP（动态服务器网页）时，我们推荐使用本地服务器。通过使用本地服务器（ADE.exe），你可以确保每一个web应用程序，或者甚至每一个会话使用ADE.exe的不同版本。当前，在ADE中有一个限制阻止同时建立两个或者多个进程内服务器对象。因此，如果你想同时有多个ADE会话（同基于web的应用程序基本完全一样），总是使用ADE本地服务器。 

在Visual Studio 2005中的.NET项目中

使用ADE COM 接口

在Visual Studio 2005中的Visual Basic、C#、J#、ASP.NET、或者 C++/CLR项目中，你可以通过在你项目中向其添加一个引用来访问ADE。旧的Visual Basic版本（pre-.NET）和少数其他非Microsoft开发环境该方法稍微有点变化。

在Visual Studio 2005中，选择Project （项目）菜单上选择 Add reference or References（添加引用），在出现的对话框中，选择COM标签（在VC++中你必须点击Add new reference按钮来获得COM标签）。在组件列表中，找到并选择下面其中的一个：

Analytica Decision Engine Local Server 4.6

Analytica Decision Engine Server 4.6

对于进程外 ADE.exe服务器，选择Local server（本地服务器）。要使用Adew.dll，选择nonlocal server（非本地服务器）。当然也可能对一个项目添加这两个引用（示例AdeTest就是这样做的），但是这很少见。

对于本地服务器和进程内服务器，ADE类型出现在同一名称空间。为了方便起见，你可以添加using声明到你的源文件的顶部，如下所示

Imports ADE ’ Visual basic

using ADE; // C#

using namespace ADE; // C++/CLR

import ADE.*; // J#

当然，在使用进程内服务器时，你将在上面的ADE的地方输入ADEW 。这些声明允许你在你的代码证引用CAEngine、CAObject等等，而非ADE.CAEngine、 ADE.CAObject等，这使从本地ADE服务器装换成进程内服务器非常容易。

在开始使用ADE之前，你必须先先安装CAEngine，按照如下所示完成：:dim ADE as CAEngine = new CAEngineClass ’ VB

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

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

CAEngine是一个特殊抽象接口的名称，而ADEW.CAEngineClass和ADE.CAEngineClass是执行该结构的两个特殊对象的名称。CAEngineClass是唯一你能直接建立的对象；所有其他ADE对象实例是通过调用现有对象上的方法来获取的。

要继续使用COM接口，你得使用CAEngine、CAObject、CATable、CAIndex和CARenderingStyle等类型名称声明你的变量。避免分配对象实例给声明为System.Object的变量。这允许编译器执行初期绑定和类型检查。

.释放NET中的对象

在pre-.NET Visual Basic和脚本语言中，编程环境自动确保COM对象立即释放。这和在VB.NET、ASP.NET、或其他.NET程序中情况不一样。当释放对象贯穿真个程序时，程序从.NET明确释放每一个COM对象非常重要。将一个指针设置成Null（或者Nothing）是不够的，因为实际释放知道下一个垃圾回收菜发生。

要想从.NET程序释放一个COM对象的话，你必须执行下面相似的代码（C# 语法）：

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

ADE = null;

在你使用一个进程外COM服务器（例如：ADE.CAEngine）时，以这种方式释放对象尤其重要。在此情况下，内存资源主要被ADE进程消耗，而不是被你的程序进程。这可能导致在你的程序使用足够的内存之前，ADE进程用完内存，导致自动垃圾回收发生。基于.NET的web应用程序的ADE.exe旧进程在一个会话完成后将长时间存在，除非你明确释放CAEngine对象。

需要释放COM对象不是ADE特有的。你必须处理释放所有COM对象，包括Microsoft提供的，尤其是当这些COM对象时进程外的时候。

因为.NET中缺少这种确定性资源回收，所以确保所有COM对象都被释放让人感到很厌烦。一次，你可能偶尔想在你的代码中执行明确的垃圾回收，以此释放所有无用对象。可以通过调用下面的函数完成：

System.GC.Collect()

在C++ATL项目中

如果要在一个非.NET C++项目中使用ADE 4.6，将下面两行放在源文件的顶部：

#import "ADE.exe"

using namespace ADE;

或者如果你想使用进程内服务器时，可以使用下面的语句：

#import "Adew.dll"

using namespace ADEW;

你必须将ADE根目录包含到项目设置中的包含路径中，或者在#import声明中清楚说明完整路径。

接下来，使用下面的代码获取第一个ADE引擎实例：

CoInitialize(NULL);

CAEnginePtr pAde(__uuidof(_CAEngine));

.

.

.

CoUninitialize();

CoInitialize()是一个Windows系统调用，在COM系统能够使用之前必须调用。

如果你的项目跨越多个代码文件，在你的每个源文件中使用以下代码：

#import "ADE.exe" no_implementation

然后只在一个文件中（比如所stdafx.cpp）包含以下代码：#import "ADE.exe" implementation_only

使用ADE自动化接口

VBScript是一个脚本语言示例，可以在Windows脚本主机（CScript.exe或 WScript.exe）、动态服务器页面pre-.NET版本、Internet Explorer等环节下使用。JScript是另一种可以使用的脚本语言，还有其他许多脚本 OLE（对象链接和嵌入）自动化编译脚本语言可以使用，其中包含Perl语言。

这些脚本语言支持ActiveX自动化脚本，但是不支持COM接口。通过使用自动化接口，ADE能够在这些语言中使用，通常不需要其他工具，只需要一个简单的文本编辑器。

对于ADE4.6之前的版本，自动化接口是使用首选。对于支持直接调用COM的语言，ADE4.6中推荐首选COM接口。在C++或C#使用自动化接口是相当单调乏味的，在此我们没有叙述。

在Visual Basic或 VBScript中使用

要使用自动化接口，没有必要给你的Visual Basic项目添加参考。下面的语法和其他脚本语言中使用情况相似。在Visual Basic中，实例化CAEngine的代码如下：

dim ADE as Object

ADE = CreateObject("ADE4.CAEngine")

在VBScript和更早的Visual Basic版本，set关键字是必须的：

dim ADE

set ADE = CreateObject("ADE4.CAEngine")

对于进程内服务器，将参数ADEW4.CAEngine发送给 CreateObject调用。

ADE Typescript语言：指令语言通讯

CAEngine类型的Command属性和Send方法允许你使用typeScript指令，作为ASCII字符串发送给引擎，并获取同为ASCII字符串的输出结果。在以下情况中，你可能更偏向于使用typescript指令：

• 你想自己对来自Analytica决策引擎，以逗号隔开的文本字符串形式的ADE输出（例如一个列表数据）执行解析。
• 不存在合适的API方法。

你可以通过执行以下操作将typescript指令发送给ADE： !将包含该指令的一个文本字符串赋值给你的CAEngine对象的Command（指令）属性。

1. 使用 Send方法将指令发送给引擎。如果Send方法返回True，那么ADE处理的指令没有错误。
2. 如果返回代码为非零，将错误代码和错误文本存储起来。这两条信息分别存储在CAEngine属性CAEngine::ErrorCode 和ErrorText中。
3. 通过调用Send类型中的OutputBuffer函数获取输出。

注意：你也可以通过调用CAEngine.SendCommand(cmd)。将前两步合并到其中。

这些步骤在下面各种编程语言中有演示说明。在这些简单示例后面，跟了几个使用Visual Basic语法的例子，你应该能够推断使用了何种语言。

在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

在VBScript中

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

在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;

}

}

}

}

在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();

}

}

}

在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;

}

}

在VC++中 （不带 .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();

}

错误与错误处理

在进行任何ADE操作后，只要可能存在错误，就必须查询CAEngine的ErrorCode和ErrorText属性。读取ADE对象属性的一个值不会改变错误代码。设置属性值可能导致错误发生，通常说明该属性的值不合理。如果不存在错误所有方法调用都将ErrorCode设置为0，或者设置成表示该错误的值。

要获取关于一个错误的额外信息，检查CAEngine的OutputBuffer属性即可。任何Analytica用户中的错误信息

另请参考

ADE入门教程 <-

使用ADE服务器

-> 在ADE中处理模型、模块和文件