1. Oracle Essbaseデータベース管理者ガイド
  2. ブロック・ストレージ・キューブの計算スクリプトの開発
  3. Essbaseでの計算スクリプト実行におけるランタイム代替変数

Essbaseでの計算スクリプト実行におけるランタイム代替変数

ランタイム代替変数(RTSV)を使用すると、メンバー名をハード・コーディングするのではなく、Essbase計算スクリプトで動的に参照できます。ランタイム代替変数は、計算スクリプト内で、代替変数が使用可能な任意の場所に含めることができます。

計算スクリプトでは、ランタイム代替変数の名前の前にアンパサンド(&)を付ける必要があります。

計算スクリプトで使用されるすべてのランタイム代替変数は、SET RUNTIMESUBVARS計算コマンドで、名前とデフォルト値を使用して宣言する必要があります。

ノート:

SET RUNTIMESUBVARSのランタイム代替変数宣言にデフォルト値が含まれていない場合、計算スクリプトの検証時にエラーが発生します。検証エラーを回避するためにデフォルト値を指定し、計算スクリプトを実行するときに予想値を指定することをお薦めします。ただし、デフォルト値を指定しない場合でも、execute calculation MaxL文をwith runtimesubvars文法とともに使用して、実行時に値を指定できます。

ランタイム代替変数のデータ型およびデータ入力制限の説明は、<RTSV_HINT>rtsv_description</RTSV_HINT>タグ内の文字列です。このタグは、ランタイム代替変数を含む計算スクリプトがEssbaseで実行される場合はオプションです。「Essbaseでの計算スクリプト実行におけるランタイム代替変数のヒント」を参照してください。ランタイム代替変数を含む計算スクリプトをSmart Viewで実行する場合は、追加のメタデータを含む<RTSV_HINT>タグが必要です。「Smart Viewでの計算スクリプト実行におけるランタイム代替変数」を参照してください。

SET RUNTIMESUBVARSの次の例では、myMarket、salesNumおよびpointDの3つのランタイム代替変数が宣言されています。各ランタイム代替変数にはデフォルト値が設定されています(たとえば、myMarketの値は"New York"です)。この例は、Essbaseで実行される計算スクリプトに適用されます。 

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

SET RUNTIMESUBVARSコマンドで指定されたデフォルト値は、実行時に、次のいずれかの方法を使用して上書きできます。

  • キー/値ペアの文字列としてランタイム代替変数が指定されたwith runtimesubvars文法でのexecute calculation MaxL文。

    前述の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)

キー/値ペアの文字列としてランタイム代替変数を指定する場合は、文字列を一重引用符で囲み、キー/値ペアをセミコロン(文字列の最後のランタイム代替変数の後、および末尾の一重引用符の前のセミコロンを含む)で区切る必要があります。このランタイム代替変数文字列の例では、4つのランタイム代替変数の名前と値が指定されています(たとえば、"a"という名前のランタイム代替変数の値は100です)。 

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

ランタイム代替変数をテキスト・ファイルに指定する場合は、.rsvという拡張子のテキスト・ファイルをクライアント・コンピュータ上に作成します。(Essbaseでは、Essbaseサーバー・コンピュータにあるランタイム代替変数ファイルはサポートされません。)ファイルの各行には、キー/値ペアとして1つのランタイム代替変数を指定し、最後にセミコロンを付ける必要があります。この.rsvファイルの例では、4つのランタイム代替変数の名前と値が指定されています。 

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

計算が実行されると、ランタイム代替変数値が次の順序で決定されます。

  1. with runtimesubvars文法でのexecute calculation MaxL文またはAPI (IEssCube.calcFileWithRunTimeSubVars Java APIまたはIEssCube.calcFileWithRunTimeSubVarFile Java API; EssCalcWithRuntimeSubVars C APIまたはEssCalcFileWithRuntimeSubVars C API)で指定された値。

  2. SET RUNTIMESUBVARS計算コマンドに指定されたデフォルト値。

ランタイム代替変数を使用する際には、次のガイドラインを考慮してください。

  • SET RUNTIMESUBVARSにランタイム代替変数を宣言したが、計算スクリプトでランタイム代替変数を使用しない場合、Essbaseは未使用のランタイム代替変数の宣言を無視します(警告や例外は生成されません)。

  • ランタイム代替変数は代替変数よりも優先されます。そのため、代替変数とランタイム代替変数の名前が同じ(たとえば、myProduct)の場合、ランタイム代替変数の値で、代替変数の値が上書きされます。

  • 複数のランタイム代替変数の名前が同じで値が異なる場合は、ランタイム代替変数の最初のインスタンスの値のみが使用されて、後続の他のすべての値は無視されます。

ランタイム代替変数の名前と値の設定ルールは、代替変数の場合と同じです。「許可される代替変数の名前と値」を参照してください。

Essbaseでの計算スクリプト実行におけるランタイム代替変数のヒント

ランタイム代替変数を使用するEssbase計算スクリプトを設計する場合、RTSV_HINTを使用して、実行時にユーザーに値を入力するように求めるテキストを含めることができます。

このトピックの情報は、Smart Viewではなく、EssbaseジョブまたはAPIでランタイム代替変数を含む計算スクリプトを実行する場合に適用されます。

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ファイルに指定されているキー/値ペアのリスト)ごとにアプリケーション・ログに1つのエントリが書き込まれます。

次の例では、2つのランタイム代替変数(EntityとCurrency)およびそれらの値が1つのエントリとしてログに書き込まれます。

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

関連項目

ENABLERTSVLOGGING