Runtime Substitution Variables in Calculation Scripts Run in Essbase

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

通过运行时替代变量 (RTSV)，您可以在 Essbase 计算脚本中动态引用成员名称，而不是对其进行硬编码。可以在允许使用替代变量的情况下，在计算脚本中包括运行时替代变量。

在计算脚本中，与号 (&) 必须位于运行时替代变量的名称之前。

计算脚本中使用的每个运行时替代变量必须在 SET RUNTIMESUBVARS 计算命令中声明，并带有名称和默认值。

注意：

如果在 SET RUNTIMESUBVARS 的运行时替代变量声明中未包含默认值，则在验证计算脚本时会发生错误。Oracle 建议您提供默认值以避免验证错误，并在运行计算脚本时提供预期值。但是，如果不提供默认值，您仍然可以在运行时使用 execute calculation MaxL 语句和 with runtimesubvars 语法提供值。

运行时替代变量的数据类型和数据输入限制的说明是 <RTSV_HINT>rtsv_description</RTSV_HINT> 标记中的字符串。在 Essbase 中运行具有运行时替代变量的计算脚本时，此标记是可选的；请参阅在 Essbase 中运行计算脚本时运行时替代变量的提示。在 Smart View 中运行具有运行时替代变量的计算脚本时，需要具有附加元数据的 <RTSV_HINT> 标记。请参阅在 Smart View 中运行计算脚本中的运行时替代变量。

在此 SET RUNTIMESUBVARS 示例中，声明了三个运行时替代变量：myMarket、salesNum 和 pointD。为每个运行时替代变量指定默认值（例如，myMarket 的值是 "New York"）。此示例适用于在 Essbase 中运行的计算脚本：

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

在运行时，可以使用以下方法之一覆盖在 SET RUNTIMESUBVARS 命令中指定的默认值：

execute calculation 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 调用或按键/值对字符串指定的 API 调用：IEssCube.calcFileWithRunTimeSubVarFile (Java API) 或 EssCalcFileWithRuntimeSubVars (C API)

将运行时替代变量指定为键/值对字符串时，必须用单引号将字符串括起来，并且键/值对必须用分号分隔，包括字符串中最后一个运行时替代变量之后和终端单引号之前的分号。在此运行时替代变量字符串示例中，指定了四个运行时替代变量的名称和值（例如，名为 "a" 的运行时替代变量的值为 100）：

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

在文本文件中指定运行时替代变量时，在客户机计算机上创建扩展名为 .rsv 的文本文件。（ Essbase 不支持位于 Essbase Server 计算机上的运行时替代变量文件。）文件中的每一行都指定一个运行时替代变量作为键/值对，并且必须以分号结尾。在 .rsv 文件的此示例中，指定了四个运行时替代变量的名称和值：

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

执行计算时，将按以下顺序确定运行时替代变量值：

通过执行计算 MaxL 语句和 with runtimesubvars 语法或 API（IEssCube.calcFileWithRunTimeSubVars 或 IEssCube.calcFileWithRunTimeSubVarFile Java APIs；EssCalcWithRuntimeSubVars 或 EssCalcFileWithRuntimeSubVars C APIs）指定的值。
在 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 Server 、应用程序或数据库级别实施日志记录。

运行时替代变量日志条目将写入到应用程序日志文件。Essbase 为每个键/值对字符串（或使用 IEssCube.calcFileWithRunTimeSubVarFile Java API 或 EssCalcFileWithRuntimeSubVars C API 时，或者在 .rsv 文件中指定的键/值对列表）将一个条目写入应用程序日志。

在以下示例中，两个运行时替代变量（实体和货币）及其值记录在一个条目中：

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

另请参见

启用日志记录