開發自訂計算巨集

27 開發自訂定義的計算巨集

Essbase 自訂巨集 (CDM) 可讓您將多個計算函式結合成單一函式。您可以在計算命令檔或公式中使用它們。

在本機測試應用程式中建立及測試新巨集。只有在您已在測試應用程式中測試 CDM，並準備在生產環境中使用 CDM 之後，才可全域註冊。

若要建立及管理 CDM，您必須具備「資料庫管理程式」權限或更高權限。

區塊儲存立方體只支援 CDM。

名稱自訂巨集

Essbase 自訂巨集 (CDM) 名稱必須是唯一的，並以 @ 符號開頭。本機巨集的前面會加上應用程式名稱。

命名 CDM 時，請遵循下列準則：

以「@」符號開始巨集名稱；例如，@MYMACRO。名稱的其餘部分可包含字母、數字及下列符號：@、#、$ 及 _。巨集名稱不可包含空格。
對於僅由其他巨集呼叫的巨集，以「@_」開頭巨集名稱，以區別巨集和一般使用的巨集和函式。
提供巨集的唯一名稱。此外，巨集名稱必須不同於自訂函式的名稱，以及現有計算函式的名稱。

附註：

如果應用程式包含的本機巨集名稱與全域巨集相同，則本機巨集會優先採用並用於計算。
對於本機巨集，必須在巨集名稱前面加上應用程式名稱，以句點分隔應用程式名稱與巨集名稱：

AppName.@MacroName

舉例而言：
```
Sample.@MYMACRO
```
由於全域巨集可用於任何在建立巨集的 Essbase 伺服器上執行的應用程式，因此您不需為其指派應用程式名稱。

建立自訂巨集

當您建立自訂的巨集 (CDM) 時， Essbase 會將其登錄到目錄中。您的巨集可以是全域或本機應用程式。然後您可以在公式和計算指令集中使用該巨集，直到該巨集從目錄中移除為止。

您可以使用下列方式註冊 CDM：

以本機為例，巨集只能在建立它的 Essbase 應用程式中使用
在全域情況下，巨集可用於在建立巨集的 Essbase 伺服器上執行的所有 Essbase 應用程式

若要建立 CDM：

使用 create macro MaxL 敘述句。

下列 MaxL 陳述式會建立名為 @COUNTRANGE 的本機巨集，以用於 Sample 應用程式中：

create macro Sample.'@COUNTRANGE'(Any) AS
'@COUNT(SKIPMISSING, @RANGE(@@S))'
spec '@COUNTRANGE(MemberRange)'
comment 'counts all non-missing values';

下列 MaxL 陳述式會建立名為 @COUNTRANGE 的全域巨集：

create macro'@COUNTRANGE'(Any) AS
'@COUNT(SKIPMISSING, @RANGE(@@S))'
spec '@COUNTRANGE(MemberRange)'
comment 'counts all non-missing values';

實行自訂巨集

使用自訂巨集 (CDM) 的方式與使用 Essbase 原生計算命令的方式相同：在計算命令檔中呼叫它們，或將它們與大綱公式建立關聯。

使用 CDM：

建立或開啟現有的計算指令碼或公式。
- 如果已在本機註冊，則必須在建立巨集的應用程式中使用計算指令集或公式。
- 如果已全域登錄，您可以在 Essbase 伺服器的任何應用程式中使用任何計算指令碼或公式。
將 CDM 新增至計算命令檔或公式。
例如，若要使用本章先前顯示的 @COUNTRANGE 自訂巨集，請建立下列計算指令碼：
```
CountMbr = @COUNTRANGE(Sales, Jan:Dec);
```
將此計算命令檔與 Sample.Basic 資料庫搭配使用，或將 "Sales, Jan:Dec" 取代為測試資料庫中的成員範圍。
儲存計算命令檔或公式，然後如常執行。

檢視自訂巨集

檢視 Essbase 中的自訂已定義巨集 (CDM)，以判斷其是否已成功建立，以及是否為範圍內的本機或全域巨集。

若要檢視 CDM，請使用 display macro MaxL 敘述句。

範例

下列 MaxL 陳述式僅顯示範例應用程式中定義的巨集：

display macro on application Sample;

下列 MaxL 陳述式會顯示所有全域與本機巨集 (如果您具有檢視權限)：

display macro;

更新自訂巨集

若要變更 Essbase 中自訂巨集 (CDM) 的語法或行為，請先判斷其在範圍中是本機還是全域，然後使用 MaxL 陳述式建立或取代巨集來更新其定義。

更新 CDM：

決定巨集是在本機還是全域註冊。

請參閱檢視自訂巨集。
若要更新巨集定義，請使用 create macro MaxL 敘述句。

範例

下列 MaxL 陳述式會變更本機巨集 @COUNTRANGE，此巨集僅用於 Sample 應用程式中：

create or replace macro Sample.'@COUNTRANGE'(Any)
as '@COUNT(SKIPMISSING, @RANGE(@@S))';

下列 MaxL 陳述式會變更全域巨集 @COUNTRANGE：

create or replace macro '@COUNTRANGE'(Any)
as '@COUNT(SKIPMISSING, @RANGE(@@S))';

複製自訂巨集

您可以將自訂巨集 (CDM) 複製到任何您具有適當存取權的 Essbase 伺服器和應用程式。您的應用程式權限層級必須為「資料庫管理員」或更高層級。

若要複製 CDM，請使用 create or replace macro MaxL 敘述句。

範例

下列 MaxL 陳述式會建立 @COVARIANCE 巨集的副本：

create macro Sample.'@COVARIANCE2'(single, single) as '@COVARIANCE'(single, single);

移除自訂巨集

若要從 Essbase 移除自訂的巨集 (CDM)，請先判斷其為範圍內的本機或全域巨集，然後使用 MaxL drop macro 陳述式。

移除 CDM：

決定巨集是在本機還是全域註冊。

請參閱檢視自訂巨集。
驗證沒有計算命令檔或公式正在使用 CDM。
若要從巨集目錄移除巨集，請使用 drop macro MaxL 陳述式。
重新啟動與該巨集相關聯的所有應用程式。

請參閱重新整理自訂巨集的目錄。

下列 MaxL 陳述式會移除僅用於 Sample 應用程式的本機巨集 @COUNTRANGE：

drop macro Sample.'@COUNTRANGE';

下列 MaxL 陳述式會移除全域巨集 @COUNTRANGE：

drop macro '@COUNTRANGE';

重新整理自訂巨集的目錄

新增、更新或移除巨集之後，請重新整理自訂巨集 (CDM) 的 Essbase 目錄。如果變更是本機變更，請使用 MaxL 陳述式重新整理自訂定義；如果變更是全域變更，請使用重新啟動 Essbase 伺服器。

若要重新整理伺服器上所有應用程式之 CDM 的目錄，請重新啟動伺服器。請參閱啟動、停止及檢查伺服器以瞭解獨立部署，或參閱使用命令啟動、停止及檢視處理作業狀態以瞭解 OCI 上的堆疊部署。

若要重新整理一個應用程式的 CDM 目錄，請使用重新整理自訂定義 MaxL 敘述句。

例如，下列 MaxL 陳述式會重新整理 Sample 應用程式的 CDM 目錄：

refresh custom definition on application sample;