Variables de substitution d'exécution dans des scripts de calcul exécutés dans Essbase

Les variables de substitution d'exécution (RTSV) vous permettent de référencer dynamiquement les noms de membre dans les scripts de calcul Essbase au lieu de les coder en dur. Une variable de substitution d'exécution peut être incluse dans un script de calcul lorsque les variables de substitution sont autorisées.

Dans un script de calcul, une esperluette (&) doit précéder le nom de la variable de substitution d'exécution.

Chaque variable de substitution d'exécution utilisée dans un script de calcul doit être déclarée dans la commande de calcul SET RUNTIMESUBVARS, avec un nom et une valeur par défaut.

Remarques :

Si aucune valeur par défaut n'est incluse dans la déclaration de variable de substitution d'exécution dans SET RUNTIMESUBVARS, une erreur se produit lorsque le script de calcul est validé. Oracle recommande de fournir une valeur par défaut pour éviter l'erreur de validation et, lors de l'exécution du script de calcul, de fournir la valeur attendue. Toutefois, si vous n'indiquez pas de valeur par défaut, vous pouvez toujours fournir une valeur lors de l'exécution à l'aide de l'instruction Execute Calculation MaxL avec la grammaire with runtimesubvars.

Une description du type de données et de la limite d'entrée de données de la variable de substitution d'exécution est une chaîne dans la balise <RTSV_HINT>rtsv_description</RTSV_HINT>. Cette balise est facultative lorsque le script de calcul avec des variables de substitution d'exécution est exécuté dans Essbase. Reportez-vous à Conseils pour les variables de substitution d'exécution dans les scripts de calcul exécutés dans Essbase. La balise <RTSV_HINT>, avec des métadonnées supplémentaires, est requise lorsque le script de calcul avec des variables de substitution d'exécution est exécuté dans Smart View. Reportez-vous à Variables de substitution d'exécution dans des scripts de calcul exécutés dans Smart View.

Dans cet exemple de SET RUNTIMESUBVARS, trois variables de substitution d'exécution sont déclarées : myMarket, salesNum et pointD. Des valeurs par défaut sont indiquées pour chaque variable de substitution d'exécution (par exemple, la valeur de myMarket est "New York"). Cet exemple s'applique à un script de calcul exécuté dans Essbase :

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

Lors de l'exécution, les valeurs par défaut spécifiées dans la commande SET RUNTIMESUBVARS peuvent être écrasées à l'aide de l'une des méthodes suivantes :

exécutez l'instruction de calcul MaxL avec la grammaire with runtimesubvars, dans laquelle les variables de substitution d'exécution sont spécifiées en tant que chaîne de paires clé/valeur.

A l'aide de l'exemple SET RUNTIMESUBVARS ci-dessus, lors de l'exécution, vous pouvez remplacer la valeur par défaut salesNum de 10 par 500 à l'aide de l'instruction MaxL suivante :
```
execute calculation appname.dbname.calcScriptName with runtimesubvars 'salesNum=500';
```
L'utilisation de cette instruction MaxL permet également de fournir des valeurs pour les variables de substitution d'exécution qui n'ont pas de valeur par défaut dans la déclaration SET RUNTIMESUBVARS.
Appel d'API dans lequel les variables de substitution d'exécution sont spécifiées en tant que chaîne de paires clé/valeur : IEssCube.calcFileWithRunTimeSubVars (API Java) ou EssCalcWithRuntimeSubVars (API C)
Appel d'API dans lequel les variables de substitution d'exécution peuvent être spécifiées dans un fichier texte sur l'ordinateur client ou sous la forme d'une chaîne de paires clé/valeur : IEssCube.calcFileWithRunTimeSubVarFile (API Java) ou EssCalcFileWithRuntimeSubVars (API C)

Lorsque vous spécifiez des variables de substitution d'exécution en tant que chaîne de paires clé/valeur, la chaîne doit être placée entre apostrophes et les paires clé/valeur doivent être séparées par un point-virgule, y compris un point-virgule après la dernière variable de substitution d'exécution dans la chaîne et avant le guillemet unique terminal. Dans cet exemple de chaîne de variable de substitution d'exécution, le nom et la valeur de quatre variables de substitution d'exécution sont indiqués (par exemple, la valeur de la variable de substitution d'exécution nommée "a" est 100) :

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

Lorsque vous indiquez des variables de substitution d'exécution dans un fichier texte, créez le fichier texte avec l'extension .rsv sur l'ordinateur client. (Essbase ne prend pas en charge les fichiers de variables de substitution d'exécution situés sur l'ordinateur Essbase Server.) Chaque ligne du fichier indique une variable de substitution d'exécution en tant que paire clé/valeur et doit se terminer par un point-virgule. Dans cet exemple de fichier .rsv, le nom et la valeur de quatre variables de substitution d'exécution sont indiqués :

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

Lorsqu'un calcul est exécuté, les valeurs des variables de substitution d'exécution sont déterminées dans l'ordre suivant :

Valeurs indiquées via l'instruction MaxL d'exécution du calcul avec la grammaire with runtimesubvars ou les API (IEssCube.calcFileWithRunTimeSubVars ou IEssCube.calcFileWithRunTimeSubVarFile API Java, EssCalcWithRuntimeSubVars ou EssCalcFileWithRuntimeSubVars C API).
Valeurs par défaut spécifiées dans la commande de calcul SET RUNTIMESUBVARS.

Tenez compte des consignes suivantes lorsque vous utilisez des variables de substitution d'exécution :

Si vous déclarez une variable de substitution d'exécution dans SET RUNTIMESUBVARS mais que vous n'utilisez pas la variable de substitution d'exécution dans le script de calcul, Essbase ignore la déclaration de variable de substitution d'exécution non utilisée (aucun avertissement ou exception n'est généré).
Les variables de substitution d'exécution ont une priorité plus élevée que les variables de substitution. Par conséquent, si une variable de substitution et une variable de substitution d'exécution portent le même nom (par exemple, myProduct), la valeur de la variable de substitution d'exécution écrase la valeur de la variable de substitution.
Si plusieurs variables de substitution d'exécution portent le même nom mais ont des valeurs différentes, seule la valeur de la première instance de la variable de substitution d'exécution est utilisée ; toutes les autres valeurs suivantes sont ignorées.

Les règles de définition de noms et de valeurs pour les variables de substitution d'exécution sont les mêmes que pour les variables de substitution. Reportez-vous à Noms et valeurs de variable de substitution autorisés.

Conseils d'exécution des variables de substitution d'exécution dans des scripts de calcul exécutés dans Essbase

Lorsque vous concevez des scripts de calcul Essbase qui utilisent des variables de substitution d'exécution, vous pouvez utiliser RTSV_HINT pour contenir du texte afin d'inviter les utilisateurs à saisir des valeurs lors de l'exécution.

Les informations de cette rubrique s'appliquent à l'exécution d'un script de calcul avec des variables de substitution d'exécution dans les travaux ou l'API Essbase, plutôt que dans Smart View.

Dans la commande de calcul SET RUNTIMESUBVARS, la déclaration de variable de substitution d'exécution peut inclure la balise <RTSV_HINT>rtsv_description</RTSV_HINT>, dans laquelle rtsv_description est une chaîne qui décrit le type de données et la limite d'entrée de données (par exemple, un entier ne dépassant pas 100) pour la variable de substitution d'exécution. La chaîne rtsv_description n'est pas utilisée dans le calcul, mais peut s'avérer utile en tant qu'invite utilisateur.

Les appels d'API peuvent extraire toutes les informations (nom, valeur par défaut et description) indiquées dans la déclaration de variable de substitution d'exécution dans SET RUNTIMESUBVARS. Par exemple, vous pouvez renvoyer ces informations à l'aide de l'adresse Get Essbase Script RTSVs de l'API REST, des méthodes d'API Java IEssIterator.getCalcFileRunTimeSubVars ou IEssIterator.getCalcRunTimeSubVars, ou de l'API C EssGetRuntimeSubVars. La chaîne rtsv_description peut ensuite être utilisée pour inviter un utilisateur à saisir une valeur lors de l'exécution ou pour valider les données d'entrée avant de transmettre la valeur au script de calcul.

Dans cet exemple de SET RUNTIMESUBVARS, chaque déclaration indique le nom, la valeur par défaut et la description de la variable de substitution d'exécution :

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>;
};

Variables de substitution d'exécution de journal

Pour consigner les variables de substitution d'exécution utilisées dans un script de calcul, définissez le paramètre de configuration ENABLERTSVLOGGING sur TRUE. La journalisation peut être implémentée au niveau du serveur Essbase, de l'application ou de la base de données.

Les entrées du journal des variables de substitution d'exécution sont écrites dans le fichier journal de l'application. Essbase écrit une entrée dans le journal de l'application pour chaque chaîne de paires clé/valeur (ou une liste de paires clé/valeur spécifiée dans un fichier .rsv lors de l'utilisation de l'API Java IEssCube.calcFileWithRunTimeSubVarFile ou de l'API C EssCalcFileWithRuntimeSubVars).

Dans l'exemple suivant, deux variables de substitution d'exécution (Entity et Currency) et leurs valeurs sont consignées dans une entrée :

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

Voir aussi