在 Essbase 中執行之計算命令檔中的程式實際執行替代變數

程式實際執行替代變數 (RTSV) 可讓您在 Essbase 計算指令碼中動態參照成員名稱，而不是進行硬式編碼。執行時期替代變數可以包含在允許替代變數的計算指令檔中。

在計算命令檔中，& 符號必須在執行時期替代變數的名稱之前。

計算命令檔中使用的每一個程式實際執行替代變數，都必須在 SET RUNTIMESUBVARS 計算命令中宣告名稱和預設值。

附註：

如果預設值未包含在 SET RUNTIMESUBVARS 的執行時期替代變數宣告中，則驗證計算命令檔時會發生錯誤。Oracle 建議您提供預設值以避免驗證錯誤，並在執行計算命令檔時提供預期的值。不過，如果您未提供預設值，仍可使用執行計算 MaxL 陳述式搭配 with runtimesubvars 文法，在執行時期提供值。

程式實際執行替代變數的資料類型和資料輸入限制描述是 <RTSV_HINT>rtsv_description</RTSV_HINT> 標記中的字串。在 Essbase 中執行具有執行時期替代變數的計算指令碼時，此標籤是選擇性的；請參閱在 Essbase 中執行之計算指令碼中的執行時期替代變數提示。在 Smart View 中執行具有執行時期替代變數的計算指令碼時，需要 <RTSV_HINT> 標記 (含其他中繼資料)。請參閱在智慧型檢視中執行之計算命令檔中的程式實際執行替代變數。

在此 SET RUNTIMESUBVARS 的範例中，宣告三個執行時期替代變數：myMarket、salesNum 以及 pointD。為每個執行時期替代變數指定預設值 (例如，myMarket 的值為 "New York")。此範例適用於在 Essbase 中執行的計算命令檔： 

SET RUNTIMESUBVARS
{
   myMarket = "New York";
   salesNum = 10;
   pointD = "Actual"->"Final";
};

在執行時期，可以使用下列其中一種方法來覆寫 SET RUNTIMESUBVARS 指令中指定的預設值：

  • 執行運算式 MaxL 陳述式搭配 with runtimesubvars 文法，其中執行時期替代變數被指定為索引鍵 / 值組的字串。

    使用上述 SET RUNTIMESUBVARS 範例，在程式實際執行時，您可以使用下列 MaxL 敘述句，將 salesNum 預設值 10 覆寫為 500： 

    execute calculation appname.dbname.calcScriptName with runtimesubvars 'salesNum=500';

    使用這個 MaxL 敘述句也可讓您提供在 SET RUNTIMESUBVARS 宣告中沒有預設值的程式實際執行替代變數值。

  • 將程式實際執行替代變數指定為索引鍵 / 值組字串的 API 呼叫：IEssCube.calcFileWithRunTimeSubVars (Java API) 或 EssCalcWithRuntimeSubVars (C API)

  • 可在從屬端電腦的文字檔中指定程式實際執行替代變數，或指定索引鍵 / 值組字串的 API 呼叫：IEssCube.calcFileWithRunTimeSubVarFile (Java API) 或 EssCalcFileWithRuntimeSubVars (C API)

將程式實際執行替代變數指定為索引鍵 / 值組字串時，字串必須以單引號括住，索引鍵 / 值組必須以分號區隔，包括字串中最後一個程式實際執行替代變數之後的分號，以及結尾單引號之前。在此程式實際執行替代變數字串範例中，會指定四個程式實際執行替代變數的名稱與值 (例如，名為 "a" 的程式實際執行替代變數值為 100)： 

'a=100;b=@CHILDREN("100");c="Actual"->"Final";d="New York";'

在文字檔中指定程式實際執行替代變數時，請在從屬端電腦上建立副檔名為 .rsv 的文字檔。( Essbase 不支援位於 Essbase 伺服器電腦上的執行時期替代變數檔案。) 檔案中的每一行都會指定一個程式實際執行替代變數作為索引鍵 / 值組，而且結尾必須是分號。在 .rsv 檔案的這個範例中，會指定四個程式實際執行替代變數的名稱和值： 

a=100;
b=200;
c=@CHILDREN("100");
d=@TODATE("DD/MM/YY","10/11/12");

執行計算時，會依下列順序決定執行時期替代變數值：

  1. 透過執行計算 MaxL 陳述式與 with runtimesubvars 文法或 API (IEssCube.calcFileWithRunTimeSubVars 或 IEssCube.calcFileWithRunTimeSubVarFile Java API；EssCalcWithRuntimeSubVars 或 EssCalcFileWithRuntimeSubVars C API) 指定的值。

  2. SET RUNTIMESUBVARS 計算指令中指定的預設值。

使用程式實際執行替代變數時，請考量下列準則：

  • 如果您在 SET RUNTIMESUBVARS 中宣告執行時期替代變數，但未在計算指令碼中使用執行時期替代變數， Essbase 會忽略未使用的執行時期替代變數宣告 (不會產生警告或例外)。

  • 程式實際執行替代變數的優先順序高於替代變數。因此，如果替代變數與執行時期替代變數具有相同的名稱 (例如 myProduct)，則執行時期替代變數的值會覆寫替代變數的值。

  • 如果多個執行時期替代變數具有相同名稱但具有不同值，則只會使用執行時期替代變數第一個例項的值；會忽略所有其他後續值。

設定程式實際執行替代變數名稱與值的規則與替代變數的規則相同。請參閱允許的替代變數名稱與值。

在 Essbase 中執行之計算命令檔中的程式實際執行替代變數提示

當您設計使用執行時期替代變數的 Essbase 計算指令碼時，您可以使用 RTSV_HINT 來包含文字，以提示使用者在執行時期輸入值。

本主題中的資訊適用於在 Essbase 工作或 API 中執行含有執行時期替代變數的計算指令碼，而不是在 Smart View 中執行。

在 SET RUNTIMESUBVARS 計算命令中，程式實際執行替代變數宣告可以包含 <RTSV_HINT>rtsv_description</RTSV_HINT> 標記，其中 rtsv_description 是一個字串，可描述程式實際執行替代變數的資料類型和資料輸入限制 (例如，不大於 100 的整數)。rtsv_description 字串不會用於計算中，但可以作為使用者提示。

API 呼叫可以擷取在 SET RUNTIMESUBVARS 的程式實際執行替代變數宣告中指定的所有資訊 (名稱、預設值及描述)。例如，您可以使用 REST API 取得 Essbase 指令碼 RTSV 端點、IEssIterator.getCalcFileRunTimeSubVars 或 IEssIterator.getCalcRunTimeSubVars Java API 方法，或 EssGetRuntimeSubVars C API 傳回此資訊。rtsv_description 字串接著可用來提示使用者在執行時期輸入值，或先驗證輸入資料，再將值傳遞至計算命令檔。

在 SET RUNTIMESUBVARS 的這個範例中，每個宣告都會指定程式實際執行替代變數的名稱、預設值以及描述：

SET RUNTIMESUBVARS
{
   myMarket = "New York" <RTSV_HINT>myMarket: Input the value as a member name, such as "New York"</RTSV_HINT>;
   salesNum = 10 <RTSV_HINT>salesNum: Input the value as an integer, such as 100</RTSV_HINT>;
   pointD = "Actual"->"Final" <RTSV_HINT>pointD: Input the value as a member combination, such as "Actual"->"Final"</RTSVVAR_HINT>;
};

記錄執行時間替代變數

若要記錄用於計算指令碼的執行時期替代變數，請將 ENABLERTSVLOGGING 組態設定設為 TRUE。記錄可以在 Essbase 伺服器、應用程式或資料庫層級實作。

程式實際執行替代變數日誌項目會寫入應用程式日誌檔。Essbase 會針對每個索引鍵 / 值組字串 (或使用 IEssCube.calcFileWithRunTimeSubVarFile Java API 或 EssCalcFileWithRuntimeSubVars C API 時，在 .rsv 檔案中指定的索引鍵 / 值組清單) 將一個項目寫入應用程式日誌。

在下列範例中，兩個執行時期替代變數 (Entity 與 Currency) 及其值會記錄在一個項目中：

Executing calc script 'calcprofit.csc' with runtime substitution variables {Entity = "MyCompany"; Currency = "USD";}

另請參閱

啟用服務記錄