使用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）中没法使用。
进程内和进程外比较
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 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，按照下面步骤操作：
- 从Windows控制面板上选择管理员工具 > 组建服务.
- 注意：如果你在一台64位计算机上使用32位版本ADE，那么你必须运行：mmc comexp.msc /32
- 在DCOM Config 文件夹中找到“Analytica Decision Engine Local Server 4.6。”
- 从右鼠标快捷菜单上选择Properties（属性） ，再选择 Security（安全性）标签。
- 将Launch and Activation Permissions（启动并激活许可） 设置成Customize（自定义）然后点击Edit（编辑）
- 授予IIS使用账户本地启动以及本地激活许可。在 IIS 5通常是{computer_name}\ASPNET。在IIS 6 & 7通常为NETWORKSERVICES或者 IIS_IUSRS，在 IIS 7.5，应该设置应用程序池名称上相应的这些设置。，通常为“IIS AppPool\DefaultAppPool”。
- 保存这些设置。你可能需要重启你的机器才能完成这些改变。
当这些许可配置不正确时，在你尝试实例化的 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的任何一种方法。
File:ADETestDialog.jpg/文件：ADETestDialog.jpg
如果你点击右手边窗体中的一个对象，其对象属性将显示在收邮编，你可以设置其属性或者调用其方法。因此，你可以模拟你的程序在一个图形接口界面可能执行的一系列的步骤。
当一种方法返回一个对象时，例如，就'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是一个特殊抽象接口的名称，而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
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.
- 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.
- 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.
- 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.
在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
- Else
- Result = ADE. OutputBuffer
- End If
- End Sub
- End Module
在VBScript中
- set ADE = CreateObject("ADE4.CAEngine")
- ADE.Command = “news”
- If ADE.Send = False Then
- 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()) {
- } 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()) {
- } 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()) {
- } 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.
另请参考
| ADE 入门教程 <- | 使用ADE服务器 | -> 在ADE中处理模型、模块和文件 |
Enable comment auto-refresher