26 開發自訂定義計算函數

若要增強 Essbase 區塊儲存立方體可用的計算函數，您可以使用 Java 來開發自己的自訂函數 (CDF)。撰寫函式之後，請安裝 Java 類別，然後在全域上向 Essbase 伺服器或本機向應用程式註冊函式。

您可以在 Essbase 計算指令碼中使用自訂函數。

Essbase 不提供建立 Java 類別和封存的工具；您必須具有支援的 JDK 版本。

如需自訂函數的範例，請參閱 Java 程式碼範例。

自訂定義的函數僅適用於區塊儲存立方體 (與聚總儲存立方體無關)。

若要建立自訂函數，請使用下列工作流程。

  1. 複查自訂函數的需求：自訂函數有效性的需求

  2. 編寫一個公用 Java 類別，其中至少包含一個要作為自訂函數的公用靜態方法：建立及編譯自訂定義函數的 Java 類別

  3. 安裝 Java 類別：在 Essbase 伺服器上安裝 Java 類別

  4. 將自訂函數註冊為本機或全域函數：註冊自訂函數

自訂定義函數的有效性需求

您將 Essbase 自訂函數設計為 Java 類別中的方法。針對全域函數，請在一個類別中寫入方法。對於應用程式函數，每個應用程式使用個別的類別和 jar 檔案。在本機對一個應用程式測試函數，然後進行全域登錄。請注意支援的資料類型、變數和命名慣例。

您可以在類別中建立多個方法，以用作自訂的函數。一般而言，Oracle 建議您建立計劃在 Essbase 伺服器上的所有應用程式間使用的方法，作為單一類別中的自訂函數。不過，如果您計劃在 Essbase 伺服器的選擇性應用程式中新增將使用的自訂函數，請在個別類別中建立這些自訂函數，然後將它們新增至個別 .jar 檔案中的 Essbase 伺服器。

建立包含作為自訂函數使用之方法的多個 Java 類別時，請確認每個類別名稱都是唯一的。重複的類別名稱會導致無法辨識重複類別中的方法，而且您無法將這些方法註冊為自訂函數。

使用 Java 中的測試程式，測試 Java 類別與方法。當您滿意方法的輸出時，請將它們安裝在 Essbase 伺服器上，然後在單一測試應用程式中註冊。請勿在全球註冊函數進行測試；這樣做可使更新函數在遇到問題時更加困難。

自訂函數中的方法可以將下列支援的資料類型組合成輸入參數：

  • 布林值

  • 位元組

  • 字元

  • 繁體中文 (香港)

  • 浮點數，雙倍

  • java.lang.String

  • 短，int，長

  • 這些類型的陣列

CalcBoolean 是 Essbase 特定的資料類型，可包含三個值：TRUE、FALSE 和 #MISSING。如需其他所列資料類型的相關資訊，請參閱 JDK 文件。

此方法傳回資料類型可以是作廢或任何先前的資料類型。傳回的資料類型會轉換成 Essbase 特定的資料類型。字串對應至字串類型。布林值會對應至 CalcBoolean 資料類型。所有其他的值都會對應到雙精度浮點數類型。

附註：

Essbase 不支援以無限或非數字值傳回的雙重變數。如果這些值是從 Java 程式傳回，則可能不會在 Essbase 中正確記錄或顯示。在傳回 Essbase 之前，應先檢查無限或非數字值的雙重變數，並將其設為有限值。請參閱 JDK 文件中 Double 類別的項目。

若要建立、刪除及管理自訂函數， Essbase 需要下列安全性權限：

  • 本機、應用程式範圍的自訂函數：應用程式管理員或更高版本

  • 全域、全伺服器、自訂函數：系統管理員

當您在 Essbase 中登錄自訂函式時，會為函式提供一個名稱，該名稱用於計算指令碼與公式中，且與函式使用的 Java 類別與方法名稱不同。

請遵循下列需求來命名自訂函數：

  • 名稱的開頭為 @ 符號。其餘函數名稱可包含字母、數字及下列符號：@、#、$ 及 _。函數名稱不得包含空格。

    例如：@MYFUNCTION

  • 使用「@_」啟動僅由自訂巨集呼叫的自訂定義函式名稱，以區別它們與一般使用函式和巨集。

    例如：@_MYFUNCTION

  • 自訂函數必須具有唯一的名稱。函數名稱必須彼此不同、自訂巨集的名稱，以及現有計算函數的名稱。

  • 如果 Essbase 應用程式包含的本機函式名稱與全域函式相同，則本機函式會用於計算。

建立和編譯自訂函數的 Java 類別

若要建立和編譯 Essbase 自訂函數 (CDF) 的 Java 類別，請使用文字編輯器或 IDE (整合開發環境) 寫入類別，然後使用 javac 工具進行編譯。

以下是建立 CDF Java 類別的範例工作流程：

  1. 在文字編輯器中建立 Java 類別。

    舉例而言：

    public class CalcFunc {
  public static double sum (double[] data) {
    int i, n = data.length;
    double sum = 0.0d;
    for (i=0; i<n; i++) {
      double d = data [i];
      sum = sum + d;
    }
    return sum;
  }
}
  2. 使用 .java 副檔名來儲存檔案。

    舉例而言： 

    CalcFunc.java
  3. 瀏覽至 .java 檔案所在的目錄；在命令提示字元輸入下列命令：
    javac java_filename

    舉例而言：

    javac CalcFunc.java
  4. 解決任何編譯錯誤，直到編譯器建立副檔名為 .class 的新檔案為止。

    舉例而言：

    CalcFunc.class

在 Essbase 伺服器上安裝 Java 類別

若要將自訂定義計算函式 (CDF) 的 Java 類別安裝至 Essbase 伺服器，請編譯它們、將 jar 檔案複製到這些說明中指定的全域或應用程式層級 udf 目錄，然後重新啟動應用程式或伺服器。

Java 類別必須使用 JDK jar 工具以 JAR 檔案編譯。

若要建立 .jar 檔案並將其安裝在 Essbase 伺服器上，請執行下列動作：

  1. 瀏覽至 .class 檔案所在的目錄；在命令提示字元輸入下列命令：
    jar cf jar_filename class_filename

    舉例而言：

    jar cf CalcFunc.jar CalcFunc.class
  2. 在 Essbase 伺服器上，將 .jar 檔案複製到下列其中一個目錄 (如果目錄不存在，請建立目錄)：

    • 若為包含全域自訂函數的 .jar 檔案：

      ESSBASEPATH/java/udf/

    • 對於僅用於特定應用程式的 .jar 檔案：

      <Application Directory>/app/appname/udf/

      其中 appname 是將使用本機 CDF 的應用程式名稱。

    如果您不知道 ESSBASEPATH 或 <Application Directory> 的位置，請參閱 Essbase 平台中的環境變數。

    如果隨後將 .jar 檔案放置在其他位置，您必須修改 CLASSPATH 變數，以包含 .jar 檔案的完整路徑和檔案名稱。

  3. 如果函數只供特定應用程式使用，請重新啟動這些應用程式。否則，請重新啟動 Essbase 伺服器。請參閱啟動、停止及檢查伺服器以瞭解獨立部署，或參閱使用命令啟動、停止及檢視處理作業狀態以瞭解 OCI 上的堆疊部署。

登錄自訂函數

使用 MaxL 在 Essbase 註冊您的自訂定義函數 (CDF)。在您撰寫 Java 類別中的 CDF、編譯類別以及安裝 jar 檔案之後，就會開始註冊作業。

將 CDF 的 Java 類別編譯為 .jar 檔案，並安裝 Essbase 伺服器上的 .jar 檔案之後，您必須先註冊函數，才能在計算命令檔和公式中使用這些函數。請參閱自訂函數有效性的要求。

當您註冊全域 CDF 時， Essbase 伺服器上的所有 Essbase 應用程式都可以使用它。在將函數設為全域之前，先測試單一應用程式中的函數 (並僅在該應用程式中註冊這些函數)。

使用相同的處理程序來更新功能目錄，以更新巨集目錄。請參閱重新整理自訂巨集的目錄。

警示：

請勿註冊全域函數進行測試；這樣做會使變更它們在遇到問題時變得更困難。

若要註冊 CDF，請使用 create function MaxL 敘述句。

若要以本端範圍註冊 CDF，請包含應用程式名稱做為字首。例如，下列 MaxL 陳述式會將 CalcFunc 類別中的函數 @JSUM 註冊為本機函數，以便在 Sample 應用程式中使用： 

create function Sample.'@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';

若要以全域範圍註冊 CDF，請勿包含應用程式名稱作為前置碼。例如，下列 MaxL 陳述式會將 CalcFunc 類別中的函數 @JSUM 註冊為全域函數，以用於 Essbase 伺服器上的任何應用程式： 

create function '@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';

附註：

為 Java 方法指定輸入參數是選擇性的。如果您未指定輸入參數， Essbase 會從 Java 程式碼中的方法定義讀取這些參數。不過，如果您使用相同的方法名稱註冊多個 CDF，但使用不同的參數集，則必須分別註冊函數的每個版本，並為函數的每個版本指定參數。

導入已登錄的自訂功能

您可以在計算命令檔和公式中使用已註冊的自訂函數 (CDF)，與使用原生 Essbase 計算函數的方式相同。

若要使用已註冊的 CDF：

  1. 建立或開啟現有的計算指令碼或公式。

    • 如果 CDF 是在本機 (在特定應用程式內) 註冊，您必須在該應用程式中使用計算指令碼或公式。

    • 如果 CDF 是全域登錄，您可以使用 Essbase 伺服器上的任何計算指令碼或公式。

  2. 將函數新增至計算命令檔或公式。

    例如，若要使用 JSUM，請使用此計算命令檔：

    "New York" = @JSUM(@LIST(2.3, 4.5, 6.6, 1000.34));

    請將此計算命令檔與 Sample.Basic 範例資料庫搭配使用，或以測試資料庫中的成員名稱取代 "New York"。

  3. 儲存計算命令檔或公式，然後如常執行。

更新自訂的函數

若要更新 Essbase 自訂定義函數 (CDF)，請確定該函數在範圍中是本機還是全域函數、關閉受影響的應用程式、取代包含函數程式碼的 .jar 檔案，然後重新註冊該函數。

更新 CDF 的程序視下列情況而定：

  • 功能已在本機或全域註冊。

  • CDF 的簽名 (類別名稱、方法名稱或輸入參數) 已在 Java 程式碼中變更。

一般而言，若要更新 CDF，您必須取代包含函數程式碼的 .jar 檔案，然後重新註冊該檔案。不過，如果 CDF 的簽章未變更，而且只有一組輸入參數 (不是超載方法)，您就可以取代包含該函數的 .jar 檔案。

附註：

只有管理員才應更新全域 CDF。

若要更新 CDF：

  1. 判斷函數是本機函數還是全域函數。

    請參閱檢視自訂函數。

  2. 對 CDF 的 Java 類別進行變更，以及使用 Java 測試程式測試其輸出。
  3. 使用與上一個 .jar 檔案相同的名稱，編譯 Java 類別並將它們存檔到新的 .jar 檔案中。

    包含先前 .jar 檔案中所含之 CDF 的所有其他類別和方法。

  4. 執行動作，視您是要更新本機或全域自訂函數而定：
    1. 本機：關閉任何使用 .jar 檔案中函數的 Essbase 應用程式。
    2. 全域：關閉所有 Essbase 應用程式

    如果您不確定 Essbase 應用程式使用 .jar 檔案中的哪些函數，請關閉所有 Essbase 應用程式。

  5. 將新的 .jar 檔案複製到 Essbase 伺服器，以相同名稱取代現有的 .jar 檔案。
  6. 如果 CDF 的簽名尚未變更，請跳至步驟 8 。
  7. 若要取代 CDF，請使用 create or replace function MaxL 敘述句。例如：

    • 本機：

      create or replace function sample.'@JSUM'
as 'CalcFunc.sum';

    • 全域：

      create or replace function '@JSUM'
as 'CalcFunc.sum';
  8. 重新啟動您關閉的應用程式，這會更新目錄。

檢視自訂函數

在 Essbase 中檢視自訂函數 (CDF)，以判斷該函數是否已順利註冊，以及該函數是否為範圍內的本機或全域函數。在 CDF 建立和註冊後，才會顯示 CDF。

檢視 CDF：

使用 display function MaxL 敘述句。

例如，使用下列 MaxL 陳述式來檢視 Sample 應用程式中的 CDF 以及任何註冊的全域函數： 

display function Sample;

display function 陳述式會列出沒有應用程式名稱的全域函式，來表示它們是全域的。如果應用程式包含與全域函數名稱相同的函數，則只會列出本機函數。

移除自訂函數

若要移除 / 取消註冊 Essbase 自訂定義函數 (CDF)，請先確定它們不是使用中的函數。然後，關閉定義 CDF 的應用程式，透過發出 MaxL drop function 陳述式來移除 CDF，然後重新啟動受影響的應用程式。

移除 CDF 需要下列權限：

  • 本機：至少有應用程式的應用程式管理員權限

  • 全域：系統管理員權限

在移除 CDF 之前，您應該確認沒有計算命令檔或公式正在使用它們。全域 CDF 可用於跨 Essbase 伺服器的計算指令碼和公式中，因此您必須先確認 Essbase 伺服器上沒有使用全域 CDF 的計算指令碼或公式，再將其移除。

警示：

只有當使用者未存取 Essbase 立方體，且未執行計算常式時，才移除全域 CDF。

若要移除 CDF：

  1. 判斷函數是本機函數還是全域函數。

    請參閱檢視自訂函數。

  2. 根據您要移除本機 CDF 或全域 CDF 而定，執行動作：
    1. 本機：關閉任何使用 .jar 檔案中函數的 Essbase 應用程式。
    2. 全域：關閉所有 Essbase 應用程式。
  3. 若要移除 CDF，請使用 drop function MaxL 敘述句。例如：

    • 本機：

      drop function Sample.'@JSUM';

    • 全域：

      drop function '@JSUM';
  4. 重新啟動您關閉的應用程式，這會更新目錄。

複製自訂函數

您可以將自訂函數 (CDF) 複製到任何您具有適當存取權的 Essbase 伺服器和應用程式。

若要複製 CDF，請使用 create or replace function as MaxL 敘述句。

自訂函數的效能考量

由於自訂定義的函式是作為 Essbase 計算器架構的延伸，因此您預期 CDF 的運作效率會比原生 Essbase 計算函式低。

若要最佳化效能，請將自訂函式的使用限制為無法以原生 Essbase 計算指令和函式執行的計算，特別是在計算速度非常重要的應用程式中。