SET RUNTIMESUBVARS
The SET RUNTIMESUBVARS calculation command declares runtime substitution variables that are used in an Essbase calculation script.
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>;
};
See Also
Using Substitution, Runtime Substitution, and Environment Variables in Calculation Scripts
ENABLERTSVLOGGING configuration setting
execute calculation MaxL statement