1. Oracle Essbaseキューブの設計およびメンテナンス
  2. ブロック・ストレージ・データベース用の計算スクリプトの開発
  3. 計算スクリプトでの置換、ランタイム置換および環境変数の使用
機械翻訳について

計算スクリプトでの置換、ランタイム置換および環境変数の使用

置換変数は、頻繁に変更される情報を参照するために使用されます。環境変数は、ユーザー固有のシステム設定のプレースホルダーとして使用されます。

置換変数の一般情報は、「置換変数の使用」を参照してください。

計算スクリプトでの代替変数の使用

計算スクリプトに代替変数を含めると、Essbaseによって、代替変数が代替変数に指定した値に置換されます。 代替変数は、頻繁に変更される情報やメンバーのリストを参照する場合などに便利です。

代替変数は、サーバー・レベル、アプリケーション・レベルおよびデータベース・レベルで作成できます。 計算スクリプトで代替変数を使用するには、計算スクリプトで代替変数が使用可能である必要があります。 たとえば、データベース・レベルの代替変数は、データベース内の計算スクリプトでのみ使用できます。サーバー・レベルの代替変数は、サーバー上のすべての計算スクリプトで使用できます。

計算スクリプトで、置換変数の前にアンパサンド(&)を挿入します。 Essbaseでは、先頭のアンパサンドで始まる文字列は置換変数として扱われ、計算スクリプトを解析する前に変数が割り当てられた値に置き換えられます。

たとえば、Sample.Basicで、Qtr1を現在の四半期として計算するには、次のようにします:

  • 現在の四半期(&CurQtr)の代替変数を作成し、値Qtr1を割り当てます

  • &CurQtr代替変数を使用する計算スクリプトを作成します。 例: 

    FIX(&CurQtr)
   CALC DIM(Measures, Product);
ENDFIX

「Essbaseでの計算スクリプト実行におけるランタイム代替変数の使用」も参照してください。

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

ランタイム代替変数は、計算スクリプト内の代替変数が使用可能な任意の場所に、代替変数と同様に含めることができます。 計算スクリプトでは、ランタイム代替変数の名前の前にアンパサンド(&)を付ける必要があります。

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

ノート:

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

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

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

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

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

  • with runtimesubvars文法を使用して計算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文法またはAPI (IEssCube.calcFileWithRunTimeSubVarsまたはIEssCube.calcFileWithRunTimeSubVarFile Java API、EssCalcWithRuntimeSubVarsまたはEssCalcFileWithRuntimeSubVars C API)を使用して計算MaxL文を実行することで指定された値。

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

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

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

  • ランタイム代替変数は、代替変数より優先されます。 したがって、代替変数とランタイム代替変数の名前が同じである場合(myProductなど)、ランタイム代替変数の値によって代替変数の値が上書きされます。

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

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

Essbaseで実行される計算スクリプトのランタイム代替変数のデータ型と入力制限の指定

このトピックの情報は、Essbaseのランタイム代替変数を使用した計算スクリプトの実行に適用されます。 「Smart Viewでの計算スクリプト実行におけるランタイム代替変数の使用」も参照してください。

SET RUNTIMESUBVARS計算コマンドでは、ランタイム代替変数宣言に<RTSV_HINT> rtsv_description </RTSV_HINT>タグを含めることができます。rtsv_descriptionは、ランタイム代替変数のデータ型およびデータ入力制限(100以下の整数など)を記述する文字列です。 rtsv_description文字列は計算で使用されません。

IEssIterator.getCalcFileRunTimeSubVarsまたはIEssIterator.getCalcRunTimeSubVarsのJava APIメソッドまたはEssGetRuntimeSubVars C APIは、SET RUNTIMESUBVARSのランタイム置換変数宣言で指定されたすべての情報(名前、デフォルト値および説明)を取得します。 その後、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ファイルで指定されたキー/バリュー・ペアのリスト)ごとに、アプリケーション・ログにエントリを書き込みます。

次の例では、2つのランタイム代替変数(EntityとCurrency)とその値が1つのエントリに記録されます:

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

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

このトピックの情報は、Smart Viewのランタイム代替変数を使用した計算スクリプトの実行に適用されます。 「Essbaseでの計算スクリプト実行におけるランタイム代替変数の使用」も参照してください。

Smart Viewで起動される計算スクリプトには、ランタイム代替変数を含めることができます。

Smart Viewにランタイム代替変数を含む計算スクリプトを使用するには、SET RUNTIMESUBVARS計算コマンドのランタイム代替変数宣言に<RTSV_HINT>タグが含まれている必要があります。 また、<RTSV_HINT>タグには<svLaunch>タグが含まれている必要があります。 通常、<svLaunch>タグには、Smart Viewで計算スクリプトを実行するためのメタデータを提供する追加のXMLタグが含まれています。

Smart Viewで使用するランタイム代替変数定義の構文: 

SET RUNTIMESUBVARS
{
   rtsv = POV
   <RTSV_HINT>
      <svLaunch>
         <description>rtsv_description</description>
         <type>member | string | number</type>
         <dimension>dimName</dimension>
         <choice>single | multiple</choice>
         <allowMissing>true | false</allowMissing>
      </svLaunch>
   </RTSV_HINT>
};

ランタイム代替変数値は、データベース内の表示可能なデータ・スライスのみが計算されるように、POVに設定する必要があります。

Smart Viewでは、「計算スクリプト」ダイアログ・ボックスでランタイム代替変数を含む計算スクリプトを選択すると、SET RUNTIMESUBVARS計算コマンドでのランタイム代替変数の定義に基づいて、「実行時プロンプト」領域にフィールドが移入されます。 定義に従って計算スクリプトを実行することも、実行時プロンプトを使用してデータ型に基づいて異なる変数情報を入力することもできます。

ノート:

Smart Viewでは、SET RUNTIMESUBVARSコマンドに<RTSV_HINT><svLaunch>...</svLaunch></RTSV_HINT>タグが含まれていない場合、ランタイム代替変数を含む計算スクリプトを実行できません。

例: POVに設定されたランタイム代替変数

ランタイム代替変数をPOVに設定するには、ランタイム代替変数の値を"POV"に設定し、データ型をmemberに設定する必要があります。

デフォルトでは、Smart Viewユーザーが実行時プロンプトで別のメンバーを指定しないかぎり、計算スクリプトは実行時にPOVのアクティブなメンバーを使用します。

この例では、データベースに次のディメンションがあるとします: 勘定科目、エンティティ、期間およびシナリオ。 3つのランタイム代替変数(Entity、ScenarioおよびPeriodという名前)が定義され、各変数の値がPOVに設定されます。 ランタイム代替変数は、FIX文で&エンティティ、&シナリオおよび&期間として参照されます。 

SET RUNTIMESUBVARS {
   Entity = POV
      <RTSV_HINT>
         <svLaunch>
            <description>Entities to Copy</description>
            <type>member</type>
            <dimension>Entity</dimension>
            <allowMissing>false</allowMissing>
            <choice>multiple</choice>
         </svLaunch>
      </RTSV_HINT>;
   Scenario = POV
      <RTSV_HINT>
         <svLaunch>
            <description>Scenarios to Copy</description>
            <type>member</type> 
            <allowMissing>false</allowMissing>
            <dimension>Scenario</dimension>
            <choice>multiple</choice>
         </svLaunch>
      </RTSV_HINT>;
   Period   = POV
      <RTSV_HINT>
         <svLaunch>
            <description>Period to Copy</description>
            <type>member</type>
            <allowMissing>false</allowMissing>
            <dimension>Period</dimension>
            <choice>single</choice>
         </svLaunch>
      </RTSV_HINT>;
}
FIX(&Entity, &Scenario, &Period)
“Opening Balance” (
@PREV(“Closing Balance”);
)

ノート:

Essbaseでは、POVに設定されたランタイム代替変数を含む計算スクリプトを実行できません。

XMLタグ・リファレンス-Smart Viewのランタイム代替変数を使用した計算スクリプト

定義されたSmart View XMLタグのランタイム代替変数:

  • <RTSV_HINT>

    Smart Viewで使用するランタイム代替変数を定義するための必須タグ。

  • <svLaunch>

    ランタイム代替変数がSmart Viewで使用するために定義されていることを示す必須タグ。

    このタグは、これらのタグの親タグです: <description>、<type>、<dimension>、<choice>および<allowMissing>。

  • <description>rtsv_description</description>

    rtsv_descriptionは、ランタイム代替変数を説明する文字列です。 文字列は計算では使用されません。

  • <type>value</type>

    有効なデータ型の値は次のとおりです:

    • member-ランタイム代替変数値は、メンバー(単一メンバー名またはメンバー名のカンマ区切りリスト)またはPOVとして定義する必要があります。

      ノート:

      メンバー名は引用符で囲む必要があります。たとえば、"New York" (単一メンバー)や"New York","Florida" (メンバー名のカンマ区切りリスト)などです。

      ランタイム代替変数値がPOVに設定されている場合、<type>値はメンバーである必要があります。 <choice>タグも参照してください。

      Essbaseでは、POVに設定されたランタイム代替変数を含む計算スクリプトを実行できません。

    • string-ランタイム代替変数の値は、単一のメンバー名、メンバー名のカンマ区切りリスト(New York、Floridaなど)または日付として定義できます。

      文字列データ型を使用する場合、「メンバー選択」ダイアログ・ボックスは使用できないため、Smart Viewユーザーは正しい構文を使用する必要があります(メンバー名を引用符で囲み、複数のメンバー名をカンマで区切るか、日付の場合は日付文字列のフォーマットを計算スクリプト-mm-yyyyまたはdd-mm-yyyyで定義されているフォーマットに一致させる)。

    • number-ランタイム代替変数値は数値として定義する必要があります

  • <dimension>dimName</dimension>

    ディメンションの名前

    ノート:

    このXMLタグは、<type>値がメンバーの場合にのみサポートされます。

  • <choice>value</choice>

    有効な値は次のとおりです:

    • シングル:

      • グリッドまたはPOVに単一のメンバーがある場合は、そのメンバーが使用されます。

      • ディメンションがPOVにある場合は、アクティブなメンバーが使用されます。

      • ディメンションがPOVにあり、複数のメンバーが存在する場合、エラーが発生します。

    • 複数-グリッドまたはPOVのすべてのディメンション・メンバーが使用されます。

    ノート:

    このXMLタグは、<type>値がメンバーの場合にのみサポートされます。

  • <allowMissing>boolean</allowMissing>

    データベースにデータが存在しないデータ・セルを許可するか抑制するかを指定します。

    有効な値: trueおよびfalse。