Variáveis de Substituição de Runtime em Scripts de Cálculo Executados no Essbase

Variáveis de Substituição em Tempo de Execução em Scripts de Cálculo Executados no Essbase

As variáveis de substituição de tempo de execução (RTSVs) permitem que você faça referência dinâmica a nomes de membros em scripts de cálculo do Essbase, em vez de codificá-los. Uma variável de substituição de tempo de execução pode ser incluída em um script de cálculo sempre que as variáveis de substituição forem permitidas.

Em um script de cálculo, um E comercial (&) deve preceder o nome da variável de substituição de runtime.

Cada variável de substituição de runtime usada em um script de cálculo deve ser declarada no comando de cálculo SET RUNTIMESUBVARS, com um nome e um valor padrão.

Observação:

Se um valor padrão não for incluído na declaração da variável de substituição de tempo de execução em SET RUNTIMESUBVARS, ocorrerá um erro quando o script de cálculo for validado. A Oracle recomenda que você forneça um valor padrão para evitar o erro de validação e, ao executar o script de cálculo, forneça o valor esperado. No entanto, se você não fornecer um valor padrão, ainda poderá fornecer um valor no runtime usando a instrução executeCalculation MaxL com a gramática with runtimesubvars.

Uma descrição do tipo de dados da variável de substituição de runtime e do limite de entrada de dados é uma string na tag <RTSV_HINT>rtsv_description</RTSV_HINT>. Essa tag é opcional quando o script de cálculo com variáveis de substituição de runtime é executado no Essbase; consulte Dicas para Variáveis de Substituição de Runtime na Execução de Scripts de Cálculo no Essbase. A tag <RTSV_HINT>, com metadados adicionais, é necessária quando o script de cálculo com variáveis de substituição de runtime é executado no Smart View. Consulte Variáveis de Substituição em Runtime na Execução de Scripts de Cálculo no Smart View.

Neste exemplo de SET RUNTIMESUBVARS, três variáveis de substituição de runtime são declaradas: myMarket, salesNum e pointD. Os valores padrão são especificados para cada variável de substituição de runtime (por exemplo, o valor de myMarket é "New York"). Este exemplo se aplica a um script de cálculo executado no Essbase:

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

No runtime, os valores padrão especificados no comando SET RUNTIMESUBVARS podem ser substituídos usando um destes métodos:

Instrução execute Calculation MaxL com a gramática with runtimesubvars, na qual as variáveis de substituição de runtime são especificadas como uma string de pares de chave/valor.

Usando o exemplo de SET RUNTIMESUBVARS acima, no runtime, você pode substituir o valor padrão salesNum de 10 por 500 usando a seguinte instrução MaxL:
```
execute calculation appname.dbname.calcScriptName with runtimesubvars 'salesNum=500';
```
O uso dessa instrução MaxL também permite fornecer valores para variáveis de substituição de runtime que não tenham um valor padrão na declaração SET RUNTIMESUBVARS.
Uma chamada de API na qual variáveis de substituição de runtime são especificadas como uma string de pares de chave/valor: IEssCube.calcFileWithRunTimeSubVars (API Java) ou EssCalcWithRuntimeSubVars (API C)
Uma chamada de API na qual as variáveis de substituição de runtime podem ser especificadas em um arquivo de texto no computador cliente ou como uma string de pares de chave/valor: IEssCube.calcFileWithRunTimeSubVarFile (API Java) ou EssCalcFileWithRuntimeSubVars (API C)

Ao especificar variáveis de substituição de runtime como uma string de pares de chave/valor, a string deve estar entre aspas simples, e os pares de chave/valor devem ser separados por ponto-e-vírgula, incluindo um ponto-e-vírgula após a última variável de substituição de runtime na string e antes das aspas simples do terminal. Neste exemplo de string de variável de substituição de runtime, o nome e o valor de quatro variáveis de substituição de runtime são especificados (por exemplo, o valor da variável de substituição de runtime chamada "a" é 100):

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

Ao especificar variáveis de substituição de runtime em um arquivo de texto, crie o arquivo de texto com uma extensão .rsv no computador cliente. (O Essbase não suporta arquivos variáveis de substituição de runtime localizados no computador do Essbase Server.) Cada linha no arquivo especifica uma variável de substituição de runtime como um par de chave/valor e deve terminar com um ponto-e-vírgula. Neste exemplo de arquivo .rsv, o nome e o valor de quatro variáveis de substituição de runtime são especificados:

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

Quando um cálculo é executado, os valores das variáveis de substituição de runtime são determinados na seguinte ordem:

Valores especificados por meio da instrução MaxL de cálculo de execução com a gramática com runtimesubvars ou as APIs (IEssCube.calcFileWithRunTimeSubVars ou IEssCube.calcFileWithRunTimeSubVarFile Java APIs; EssCalcWithRuntimeSubVars ou EssCalcFileWithRuntimeSubVars C APIs).
Valores padrão especificados no comando de cálculo SET RUNTIMESUBVARS.

Considere estas diretrizes ao usar variáveis de substituição de runtime:

Se você declarar uma variável de substituição de runtime em SET RUNTIMESUBVARS, mas não usar a variável de substituição de runtime no script de cálculo, o Essbase ignorará a declaração de variável de substituição de runtime não utilizada (nenhum aviso ou exceção será gerado).
As variáveis de substituição de tempo de execução têm uma precedência maior do que as variáveis de substituição. Portanto, se uma variável de substituição e uma variável de substituição de runtime tiverem o mesmo nome (por exemplo, myProduct), o valor da variável de substituição de runtime substituirá o valor da variável de substituição.
Se várias variáveis de substituição de runtime tiverem o mesmo nome, mas tiverem valores diferentes, somente o valor da primeira instância da variável de substituição de runtime será usado; todos os outros valores subsequentes serão ignorados.

As regras para definir nomes e valores para variáveis de substituição de runtime são as mesmas das variáveis de substituição. Consulte Nomes e Valores de Variável de Substituição Permitidos.

Dicas para Variáveis de Substituição de Tempo de Execução em Scripts de Cálculo Executados no Essbase

Ao criar scripts de cálculo do Essbase que usam variáveis de substituição de tempo de execução, você pode usar o RTSV_HINT para conter texto para solicitar aos usuários valores de entrada no tempo de execução.

As informações neste tópico se aplicam à execução de um script de cálculo com variáveis de substituição de runtime em jobs ou API do Essbase, em vez de no Smart View.

No comando de cálculo SET RUNTIMESUBVARS, a declaração da variável de substituição de runtime pode incluir a tag <RTSV_HINT>rtsv_description</RTSV_HINT>, na qual rtsv_description é uma string que descreve o tipo de dados e o limite de entrada de dados (por exemplo, um número inteiro não maior que 100) para a variável de substituição de runtime. A string rtsv_description não é usada no cálculo, mas pode ser útil como um prompt do usuário.

As chamadas de API podem recuperar todas as informações (nome, valor padrão e descrição) especificadas na declaração da variável de substituição de runtime no SET RUNTIMESUBVARS. Por exemplo, você pode retornar essas informações usando o ponto final da API REST Obter RTSVs do Script Essbase, os métodos da API Java IEssIterator.getCalcFileRunTimeSubVars ou IEssIterator.getCalcRunTimeSubVars ou a API C EssGetRuntimeSubVars. A string rtsv_description pode ser usada para solicitar que um usuário insira um valor no runtime ou para validar dados de entrada antes de passar o valor para o script de cálculo.

Neste exemplo de SET RUNTIMESUBVARS, cada declaração especifica o nome, o valor padrão e a descrição da variável de substituição de runtime:

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

Registrar Variáveis de Substituição de Tempo de Execução

Para registrar variáveis de substituição de tempo de execução usadas em um script de cálculo, defina a configuração ENABLERTSVLOGGING como TRUE. O registro em log pode ser implementado no nível do Essbase Server, do aplicativo ou do banco de dados.

As entradas de log da variável de substituição de runtime são gravadas no arquivo de log do aplicativo. O Essbase grava uma entrada no log do aplicativo para cada string de pares de chave/valor (ou uma lista de pares de chave/valor especificados em um arquivo .rsv ao usar a API Java IEssCube.calcFileWithRunTimeSubVarFile ou EssCalcFileWithRuntimeSubVars C).

No exemplo a seguir, duas variáveis de substituição de runtime (Entidade e Moeda) e seus valores são registrados em uma entrada:

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

Consulte Também

ENABLERTSVLOGGING