SET RUNTIMESUBVARS

Every runtime substitution variable used in a calculation script must be declared in the SET RUNTIMESUBVARS command, with a name and a default value. You can include a description of the runtime substitution variable's data type and data input limit, which is a string in the <RTSV_HINT>rtsv_description</RTSV_HINT> tag. Each runtime substitution variable declaration must end in a semicolon.

Syntax

SET RUNTIMESUBVARS
 {
   runtime_substitution_variable [= value] [<RTSV_HINT>rtsv_description</RTSV_HINT>];
 };

Parameters

runtime_substitution_variable

Name of a runtime substitution variable

value

Default value of the named runtime substitution variable. The value can be expressed as a string, a constant, a member name, or a member combination.

Default values specified in the SET RUNTIMESUBVARS command can be overwritten at runtime. See Using Runtime Substitution Variables in Calculation Scripts Run in Essbase.

<RTSV_HINT>rtsv_description</RTSV_HINT>

A string that describes the data type and data input limit (for example, an integer not greater than 100) of the named runtime substitution variable. When running a calculation script that contains runtime substitution variables, the <RTSV_HINT> tag is:

Optional, when running the calculation script in Essbase
Required, when running the calculation script in Smart View

The IEssIterator.getCalcFileRunTimeSubVars or IEssIterator.getCalcRunTimeSubVars Java API methods or EssGetRuntimeSubVars C API retrieves all of the information (name, value, and description) that is specified in the runtime substitution variable declaration. The <RTSV_HINT> string can then be used to prompt a user to input a value at runtime or to validate input data before passing the value to the calculation script.

Notes

If a default value is not included in the runtime substitution variable declaration in SET RUNTIMESUBVARS, an error occurs when the calculation script is validated. Oracle recommends that you provide a default value to avoid the validation error and, when running the calculation script, provide the expected value. However, if you do not provide a default value, you can still provide a value at runtime using the execute calculation MaxL statement with the with runtimesubvars grammar.
If you specify a runtime substitution variable in SET RUNTIMESUBVARS but do not use the runtime substitution variable in the calculation script, Essbase ignores the runtime substitution variable declaration.
If multiple runtime substitution variables have the same name but have different values, only the value of the first instance of the runtime substitution variable is used; all other subsequent values are ignored.
To log the runtime substitution variables that are used in a calculation script, set the ENABLERTSVLOGGING configuration setting to TRUE.

Example

In the following example, three runtime substitution variables are defined with a name and a default value; for example, the runtime substitution variable named myMarket has a value of "New York".

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

In the following example, the runtime substitution variables include a default value and rtsv_description. The EssGetRuntimeSubVars API can be implemented to retrieve all of the information (name, value, and description) about the runtime substitution variable. The <RTSV_HINT> string can then be used to prompt a user to input a value at runtime or to validate input data before passing the value to the calculation script.

SET RUNTIMESUBVARS
{
   myMarket "New York" <RTSV_HINT>myMarket: Input the value as a string, 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 name or a member combination, such as "Actual"->"Final"</RTSV_HINT>;
};

The following example shows the use of XML-style tags within the <RTSV_HINT> tag for running a calculation script with runtime substitution variables in Smart View:

SET RUNTIMESUBVARS
{
   sbx = POV <RTSV_HINT>
      <svLaunch>
      <description>Sandbox to merge</description>
      <allowMissing>false</allowMissing>
      <type>member</type>
      <dimension>Sandbox</dimension>
      <choice>single</choice>
      </svLaunch>
   </RTSV_HINT>;
};