Runtime Substitution Variables in Calculation Scripts Run in Smart View

在 Smart View 中运行计算脚本中的运行时替代变量

可以在 Essbase 计算脚本中使用运行时替代变量 (runtime substitution variables，RTSV)，该计算脚本设计用于在 Smart View 中执行。RTSV 使计算的焦点区域成为动态区域，具体取决于活动网格上下文 (POV)。

要使用在 Smart View 中包括运行时替代变量的计算脚本， SET RUNTIMESUBVARS 计算命令中的运行时替代变量声明必须包括 <RTSV_HINT> 标记。此外，<RTSV_HINT> 标记必须包括 <svLaunch> 标记。通常，<svLaunch> 标记包括其他 XML 标记，这些标记提供用于在 Smart View 中执行计算脚本的元数据。

使用以下语法定义要在 Smart View 中使用的运行时替代变量定义：

SET RUNTIMESUBVARS
{
   rtsvName = 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>
};

在上面的定义中，运行时替代变量名称为 rtsvName，但您可以使用任何名称。变量的值必须设置为 POV，以指示只应计算电子表格网格中存在的当前数据切片。

<RTSV_HINT> 元素还必须是变量声明的一部分。其内容包括：

<description>：用于帮助 Smart View 用户了解成员选择的描述符
<type>：指定变量是用于成员、字符串还是数字
<allowMissing>：如果应包括缺少的数据，则为 true；否则为 false
<dimension>：此变量从中提取信息的维的名称
<choice>：如果只能将一个选择传递给运行时替代变量，则为 single；否则为 multiple。

有关上面列出的 XML 标记的完整说明，请参阅《 XML Tag Reference — Calculation Scripts with Runtime Substitution Variables for Smart View 》。

在 Smart View 中，当您在计算脚本对话框中选择包含运行时替代变量的计算脚本时，运行时提示区域会根据在 SET RUNTIMESUBVARS 计算命令中定义运行时替代变量的方式填充字段。可以按定义运行计算脚本，也可以使用运行时提示根据数据类型输入不同的变量信息。

注意：

在 Smart View 中，如果 SET RUNTIMESUBVARS 命令不包括 <RTSV_HINT><svLaunch>...</svLaunch></RTSV_HINT> 标记，则无法运行包含运行时替代变量的计算脚本。

示例：运行时替代变量设置为 POV

要将 Essbase 计算脚本的运行时替代变量设置为 Smart View 活动网格上下文 (POV)，必须将运行时替代变量的值设置为 POV，并且必须将数据类型设置为 member，如本示例中所示。

默认情况下，计算脚本在运行时使用 POV 中的活动成员，除非 Smart View 用户在运行时提示中指定其他成员。

在此示例中，假设数据库具有以下维：Account（帐户）、Entity（实体）、Period（期间）和 Scenario（方案）。定义了三个运行时替代变量（命名为 rtsvEntity、rtsvScenario 和 rtsvPeriod），并且每个变量的值都设置为 POV。在 FIX 语句中，运行时替代变量被引用为 &rtsvEntity、&rtsvScenario 和 &rtsvPeriod。

SET RUNTIMESUBVARS {
   rtsvEntity = POV
      <RTSV_HINT>
         <svLaunch>
            <description>Entities to Copy</description>
            <type>member</type>
            <dimension>Entity</dimension>
            <allowMissing>false</allowMissing>
            <choice>multiple</choice>
         </svLaunch>
      </RTSV_HINT>;
   rtsvScenario = POV
      <RTSV_HINT>
         <svLaunch>
            <description>Scenarios to Copy</description>
            <type>member</type> 
            <allowMissing>false</allowMissing>
            <dimension>Scenario</dimension>
            <choice>multiple</choice>
         </svLaunch>
      </RTSV_HINT>;
   rtsvPeriod   = 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(&rtsvEntity, &rtsvScenario, &rtsvPeriod)
"Opening Balance" (
@PREV("Closing Balance");
)

变量声明下方是一个 FIX 块，用于选择计算的焦点区域，并执行命令来设置期间的期初余额。运行时替代变量将使用此语法传递到 FIX 块：&varname。因此，计算的侧重区域是动态的，具体取决于 Smart View 中的 POV。

注意：

使用 Essbase jobs 接口、 MaxL 执行计算语句或 API（例如 REST API 执行作业端点）时，无法运行包含设置为 POV 的运行时替代变量的计算脚本。由于这些内容依赖于当前的 Smart View 网格上下文，因此必须从 Smart View 运行它们。

XML 标记引用 - 使用 Smart View 的运行时替代变量的计算脚本

在设计 Essbase 计算脚本时，如果运行时替代变量旨在基于 Smart View POV/网格上下文执行，则需要使用此处介绍的一些 XML 标记。

<RTSV_HINT>

用于定义要在 Smart View 中使用的运行时替代变量的必需标记。
<svLaunch>

指示运行时替代变量的定义用于 Smart View 的必需标记。

此标记是以下标记的父标记：<description>、<type>、<dimension>、<choice> 和 <allowMissing>。
<description>rtsv_description</description>

rtsv_description 是描述运行时替代变量的字符串。该字符串不用于计算。
<type>value</type>

有效的数据类型值包括：
- 成员 - 运行时替代变量值必须定义为成员（单个成员名称或成员名称的逗号分隔列表）或 POV。
  
  注意：
  
  成员名称必须用引号括起来；例如，"New York"（单个成员）或 "New York","Florida"（以逗号分隔的成员名称列表）。
  
  如果将运行时替代变量值设置为 POV，则 <type> 值必须是成员。另请参见 <choice> 标记。
  
  使用 Essbase 作业或 MaxL，无法运行包含设置为 POV 的运行时替代变量的计算脚本。这些计算脚本将从 Smart View 运行，因为 POV 依赖于当前网格上下文来确定分片。
- string - 运行时替代变量值可以定义为单个成员名称、以逗号分隔的成员名称列表（例如 "New York"，"Florida"）或日期。
  
  使用字符串数据类型时，成员选择对话框不可用；因此， Smart View 用户必须确保使用正确的语法（在引号中放置成员名称，使用逗号分隔多个成员名称，或者在某个日期，将日期字符串的格式与计算脚本中定义的格式（mm-dd-yyyy 或 dd-mm-yyyy）匹配。
- number - 运行时替代变量值必须定义为数字
<dimension>dimName</dimension>

维的名称。

注意：

仅当 <type> 值是成员时，才支持此 XML 标记。
<choice>value</choice>

有效选项值为：
- single：
  - 如果网格或 POV 上存在单个成员，则使用该成员。
  - 如果某个维位于 POV 上，则使用活动成员。
  - 如果某个维位于 POV 上并且有多个成员，则会出现错误。
- 多维 - 使用网格或 POV 上的所有维成员。
注意：

仅当 <type> 值是成员时，才支持此 XML 标记。
<allowMissing>boolean</allowMissing>

指定是允许还是禁止数据库中不存在其数据的数据单元格。

有效值：“真”和“假”。