EssCreateVariable

Creates a new substitution variable or modifies an existing substitution variable if the variable name already exists with the identical server, application, and database values.

Syntax

ESS_FUNC_M EssCreateVariable (hCtx, pVariable);

Parameter	Data Type	Description
hCtx	ESS_HCTX_T	API context handle.
pVariable	ESS_PVARIABLE_T	Pointer to the structure containing the description of the substitution variable being created.

Notes

The scope of the variable can apply to the server, the application, or the database. The scope is controlled through the ESS_VARIABLE_T structure. When the server, application, and database are all named, the substitution variable applies only to the specified database. When only the server and application are named, the substitution variable applies to all databases in the specified application. When only the server is named, the substitution variable applies to all applications and databases on the specified server.
When a variable exists and a new variable is created with the same name and scope, the new value replaces the old value with no error message from Essbase.
On a given server, you can create multiple substitution variables with the same name but different scopes (application and database).

Return Value

If successful, returns zero.

Example

/*
** ESS_CreateVariable() creates a substitution variable using
** the API EssCreateVariable, and sets its value.
*/
ESS_FUNC_M
ESS_CreateVariable (ESS_HCTX_T hCtx)
{
   ESS_FUNC_M      sts = ESS_STS_NOERR;
   ESS_VARIABLE_T Variable; 
   printf("\n ******************************************");
   printf("\n **** An example of using EssCreateVariable");
   printf("\n ******************************************");
   /* Create Variable 'QuarterName' at the level of the server/App/Db */
   strcpy(Variable.VarName,  "QuarterName"); 
   strcpy(Variable.Server,   "Local"); 
   strcpy(Variable.AppName,  "Sample"); 
   strcpy(Variable.DbName,   "Basic"); 
   strcpy(Variable.VarValue, "Qtr1"); 
   sts = EssCreateVariable(hCtx, &Variable);
   if (sts == ESS_STS_NOERR)
     printf("\n Variable 'QuarterName' is created at the Server/App/Db level 
     with value 'Qtr1'");
   
   /* Change Value of 'QuarterName' from Qtr1 to Qtr2 */
   if (sts == ESS_STS_NOERR)
   {
     strcpy(Variable.VarName,  "QuarterName"); 
     strcpy(Variable.Server,   "Local"); 
     strcpy(Variable.AppName,  "Sample"); 
     strcpy(Variable.DbName,   "Basic"); 
     strcpy(Variable.VarValue, "Qtr2"); 
     sts = EssCreateVariable(hCtx, &Variable);
     if (sts == ESS_STS_NOERR)
       printf("\n Variable 'QuarterName' at the Server/App/Db level is updated 
       to value 'Qtr2'");
   }
   /* Create Variable 'MarketName' at the level of the Server/App */
   if (sts == ESS_STS_NOERR)
   {
     strcpy(Variable.VarName,  "MarketName"); 
     strcpy(Variable.Server,   "Local"); 
     strcpy(Variable.AppName,  "Sample"); 
     strcpy(Variable.DbName,   ""); 
     strcpy(Variable.VarValue, "East"); 
     sts = EssCreateVariable(hCtx, &Variable);
     if (sts == ESS_STS_NOERR)
       printf("\n Variable 'MarketName' is created at the Server/App level");
   }
   /* Create Variable "MarketName' at the level of the Server */ 
   /* This shows that you can have the same variable name at different levels*/
  
   if (sts == ESS_STS_NOERR)
   {
     strcpy(Variable.VarName,  "MarketName"); 
     strcpy(Variable.Server,   "Local"); 
     strcpy(Variable.AppName,  ""); 
     strcpy(Variable.DbName,   ""); 
     strcpy(Variable.VarValue, "Market"); 
     sts = EssCreateVariable(hCtx, &Variable);
     if (sts == ESS_STS_NOERR)
       printf("\n Variable 'MarketName' is created at the Server level");
   }
   if (sts == ESS_STS_NOERR)
      printf("\n --> No Errors in EssCreateVariable\n\n\n");
   else
      printf("\n --> Error in EssCreateVariable number: %d\n\n\n", sts); 
   
   return (sts);
} /* end ESS_CreateVariable */

Output

 ******************************************
 **** An example of using EssCreateVariable
 ******************************************
 Variable 'QuarterName' is created at the Server/App/Db level with value 'Qtr1'
 Variable 'QuarterName' at the Server/App/Db level is updated to value 'Qtr2'
 Variable 'MarketName' is created at the Server/App level
 Variable 'MarketName' is created at the Server level
 --> No Errors in EssCreateVariable