EssListVariables

EssListVariables() lists substitution variables at the server, application, and database levels, according to the input criteria.

Syntax

ESS_FUNC_M EssListVariables (hCtx, pCriteria, pNumVars, ppVarList);
ParameterData TypeDescription

hCtx

ESS_HCTX_T

Context handle to the API.

pCriteria

ESS_VARIABLE_T

The pointer to the structure containing the description of the substitution variables being listed.

  • The members VarName and VarValue are ignored.

  • If the Server member is given but AppName and DbName are empty, then the function will list substitution variables at the server level only.

  • If the Server and AppName members are given but DbName is empty, it lists all variables at both the given server and application levels.

  • If all three of Server, AppName, and DbName members are given, it lists variables from all three specified levels.

  • If a field is empty, then that field is treated as a "don't care."

pNumVars

ESS_PULONG_T

The pointer to an unsigned long value indicating the number of variables being returned in the ppVarList parameter.

ppVarList

ESS_VARIABLE_T

The pointer to an array of substitution variable structures. It is the responsibility of the caller to free this array by calling EssFree.

Return Value

If successful, returns zero.

Example

/*
** ESS_ListVariables() lists the substitution variables using
** the API EssListVariables.
*/
ESS_FUNC_M
ESS_ListVariables (ESS_HCTX_T hCtx)
{
   ESS_FUNC_M         sts = ESS_STS_NOERR;
   ESS_PVARIABLE_T   pVariables;
   ESS_ULONG_T       ulCount, i;
   ESS_VARIABLE_T    Variable;
   printf("\n *****************************************");
   printf("\n **** An example of using EssListVariables");
   printf("\n *****************************************");
   /*****************************************************************/
   /* List Variables at the level of the Server/App/Db              */
   /* Variables under that specific server will be listed          */ 
   /* Variables under that specific server/ App will be listed     */ 
   /* Variables under that specific server/ App /DB will be listed */ 
   /*****************************************************************/	 
   strcpy(Variable.VarName,  "");   // ignored by EssListVariables 
   strcpy(Variable.Server,  "local");
   strcpy(Variable.AppName, "Sample");
   strcpy(Variable.DbName,  "Basic");
   sts = EssListVariables(hCtx, &Variable, &ulCount, &pVariables);
   if (sts == ESS_STS_NOERR)
   {
      printf("\n--- Number of Substitution Variables at the Server, App and Db 
        level is: %ld\n", ulCount);
      for (i = 0; i < ulCount; i++)
      {
         printf("Variable name    : %s\n",   pVariables[i].VarName);
         printf("Server name      : %s\n",   pVariables[i].Server);
         printf("Application name : %s\n",   pVariables[i].AppName);
         printf("Database name    : %s\n",   pVariables[i].DbName);
         printf("Variable value   : %s\n\n", pVariables[i].VarValue);
      }
   }
   /****************************************************************/
   /* Variables under that specific Server will be listed          */ 
   /* Variables under that specific Server/App will be listed      */ 
   /****************************************************************/
   if (sts == ESS_STS_NOERR)
   {

     strcpy(Variable.VarName,  "");   // ignored by EssListVariables
     strcpy(Variable.Server,  "local"); 
     strcpy(Variable.AppName, "Sample"); 
     strcpy(Variable.DbName,  "");
     sts = EssListVariables(hCtx, &Variable, &ulCount, &pVariables);
     if (sts == ESS_STS_NOERR)
     {
        printf("\n--- Number of Substitution Variables at the Server and App 
          level is: %ld\n", ulCount);
        for (i = 0; i < ulCount; i++)
        {
           printf("Variable name    : %s\n",   pVariables[i].VarName);
           printf("Server name      : %s\n",   pVariables[i].Server);
           printf("Application name : %s\n",   pVariables[i].AppName);
           printf("Database name    : %s\n",   pVariables[i].DbName);
           printf("Variable value   : %s\n\n", pVariables[i].VarValue);
        }
     }
   }
   /***************************************************************/
   /* List Variables at the level of the Server                   */
   /***************************************************************/
   if (sts == ESS_STS_NOERR)
   {
     strcpy(Variable.VarName,  "");   // ignored by EssListVariables
     strcpy(Variable.Server,  "local"); 
     strcpy(Variable.AppName, ""); 
     strcpy(Variable.DbName,  "");
     if (sts == ESS_STS_NOERR)
       sts = EssListVariables(hCtx, &Variable, &ulCount, &pVariables);
     if (sts == ESS_STS_NOERR)
     {
        printf("\n--- Number of Substitution Variables at the Server level is: 
          %ld\n", ulCount);
        for (i = 0; i < ulCount; i++)
        {
           printf("Variable name    : %s\n",   pVariables[i].VarName);
           printf("Server name      : %s\n",   pVariables[i].Server);
           printf("Application name : %s\n",   pVariables[i].AppName);
           printf("Database name    : %s\n",   pVariables[i].DbName);
           printf("Variable value   : %s\n\n", pVariables[i].VarValue);
        }
      }
    }

   if (sts == ESS_STS_NOERR)
      printf("\n --> No Errors in EssListVariables\n\n\n");
   else
      printf("\n --> Error in EssListVariables number: %d\n\n\n", sts); 
   
   return (sts);
} /* end ESS_ListVariables */

Output

 *****************************************
 **** An example of using EssListVariables
 *****************************************
--- Number of Substitution Variables at the Server, App and Db level is: 3
Variable name    : QuarterName
Server name      : local
Application name : Sample
Database name    : Basic
Variable value   : Qtr2
Variable name    : MarketName
Server name      : local
Application name : Sample
Database name    : 
Variable value   : East
Variable name    : MarketName
Server name      : local
Application name : 
Database name    : 
Variable value   : Market

--- Number of Substitution Variables at the Server and App level is: 2
Variable name    : MarketName
Server name      : local
Application name : Sample
Database name    : 
Variable value   : East
Variable name    : MarketName
Server name      : local
Application name : 
Database name    : 
Variable value   : Market

--- Number of Substitution Variables at the Server level is: 1
Variable name    : MarketName
Server name      : local
Application name : 
Database name    : 
Variable value   : Market

 --> No Errors in EssListVariables

See Also