使用ADE伺服器
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，按照下面步驟操作：
- 從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的任何一種方法。
如果你點擊右手邊窗體中的一個對象，其對象屬性將顯示在收郵編，你可以設置其屬性或者調用其方法。因此，你可以模擬你的程序在一個圖形接口界面可能執行的一系列的步驟。
當一種方法返回一個對象時，例如，就'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
使用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（指令）屬性。
- 使用 Send方法將指令發送給引擎。如果Send方法返回True，那麼ADE處理的指令沒有錯誤。
- 如果返回代碼為非零，將錯誤代碼和錯誤文本存儲起來。這兩條信息分別存儲在CAEngine屬性CAEngine::ErrorCode 和ErrorText中。
- 通過調用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
- 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();
- }
錯誤與錯誤處理
在進行任何ADE操作後，只要可能存在錯誤，就必須查詢CAEngine的ErrorCode和ErrorText屬性。讀取ADE對象屬性的一個值不會改變錯誤代碼。設置屬性值可能導致錯誤發生，通常說明該屬性的值不合理。如果不存在錯誤所有方法調用都將ErrorCode設置為0，或者設置成表示該錯誤的值。
要獲取關於一個錯誤的額外信息，檢查CAEngine的OutputBuffer屬性即可。任何Analytica用戶中的錯誤信息
另請參考
| ADE入門教程 <- | 使用ADE伺服器 | -> 在ADE中處理模型、模塊和文件 |
Enable comment auto-refresher