# EssCreateVariable

Description

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

ESS_HCTX_T | hCtx
ESS_PVARIABLE_T | pVariable

Parameters

hCtx | Essbase API context handle.
pVariable | Pointer to the structure containing the description of the substitution variable being created.

Return Value

If successful, returns zero.

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).

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

See Also

ESS_VARIABLE_T
EssDeleteVariable()
EssGetVariable()
EssListVariables()