DB2 Version 10.1 for Linux, UNIX, and Windows

db2CfgSet API - Set the database manager or database configuration parameters

Modifies individual entries in a specific database configuration file or a database manager configuration file. A database configuration file resides on every database partition on which the database has been created.

Scope

Modifications to the database configuration file affect all database partitions by default.

Authorization

For modifications to the database configuration file, one of the following authorities:

SYSADM
SYSCTRL
SYSMAINT

For modifications to the database manager configuration file:

SYSADM

Required connection

To make an online modification of a configuration parameter for a specific database, a connection to the database is required. To make an online modification of a configuration parameter for the database manager, an attachment to an instance is not required.

API include file

db2ApiDf.h

API and data structure syntax

SQL_API_RC SQL_API_FN
   db2CfgSet (
   db2Uint32 versionNumber,
   void * pParmStruct,
   struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2Cfg
{
   db2Uint32 numItems;
   struct db2CfgParam *paramArray;
   db2Uint32 flags;
   char *dbname;
   SQL_PDB_NODE_TYPE dbpartitionnum;
   SQL_PDB_NODE_TYPE member;
}  db2Cfg;

typedef SQL_STRUCTURE db2CfgParam
{
   db2Uint32 token;
   char *ptrvalue;
   db2Uint32 flags;
}  db2CfgParam;

SQL_API_RC SQL_API_FN
   db2gCfgSet (
   db2Uint32 versionNumber,
   void * pParmStruct,
   struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2gCfg
{
   db2Uint32 numItems;
   struct db2gCfgParam *paramArray;
   db2Uint32 flags;
   db2Uint32 dbname_len;
   char *dbname;
}  db2gCfg;

typedef SQL_STRUCTURE db2gCfgParam
{
   db2Uint32 token;
   db2Uint32 ptrvalue_len;
   char *ptrvalue;
   db2Uint32 flags;
}  db2gCfgParam;

db2CfgSet API parameters

versionNumber: Input. Specifies the version and release level of the structure passed as the second parameter pParmStruct.
pParmStruct: Input. A pointer to the db2Cfg structure.
pSqlca: Output. A pointer to the sqlca structure.

db2Cfg data structure parameters

numItems

Input. The number of configuration parameters in the paramArray array. Set this value to db2CfgMaxParam to specify the largest number of elements in the paramArray.

paramArray

Input. A pointer to the db2CfgParam structure.

flags

Input. Specifies the type of action to be taken. Valid values (defined in db2ApiDf header file, located in the include directory) are:

db2CfgDatabase: Specifies to return the values in the database configuration file.
db2CfgDatabaseManager: Specifies to return the values in the database manager configuration file.
db2CfgImmediate: Returns the current values of the configuration parameters stored in memory.
db2CfgDelayed: Gets the values of the configuration parameters on disk. These do not become the current values in memory until the next database connection or instance attachment.
db2CfgReset: Reset all database manager configuration parameters to default values.
db2CfgSingleDbpartition: To update or reset the database configuration on a specific database partition, set this flag and provide a value for dbpartitionnum. This is only applicable in a partitioned database environment and ignored in other environments.
db2CfgSingleMember: To update or reset the database configuration on a specific member, set this flag and provide a value for member. This is only applicable in a DB2® pureScale® environment and ignored in other environments.

dbname

Input. The database name.

dbpartitionnum

Input. Specifies on which database partition this API will set the configuration value. The DBPARTITIONNUM parameter is only applicable in a partitioned database environment and must be 0 in a DB2 pureScale environment.

member

Input. Specifies on which member this API will set the configuration value. The MEMBER parameter is only applicable in a DB2 pureScale environment and ignored in other environments.

db2CfgParam data structure parameters

token

Input. The configuration parameter identifier. Valid entries and data types for the db2CfgParam token element are listed in "Configuration parameters summary".

Note: Additional db2Cfg tokens are added to support getting (or setting) of cluster caching facility configuration parameters and cluster caching facility structure configuration parameters in a DB2 pureScale environment.

ptrvalue

Output. The configuration parameter value.

flags

Input. Provides specific information for each parameter in a request. Valid values (defined in db2ApiDf header file, located in the include directory) are:

db2CfgParamAutomatic: Indicates whether the retrieved parameter has a value of automatic. To determine whether a given configuration parameter has been set to automatic, perform a boolean AND operation against the value returned by the flag and the db2CfgParamAutomatic keyword defined in db2ApiDf.h.

db2CfgParamComputed: Indicates whether the retrieved parameter has a value of computed. To determine whether a given configuration parameter has been set to computed, perform a boolean AND operation against the value returned by the flag and the db2CfgParamComputed keyword defined in db2ApiDf.h.

db2CfgParamManual: Used to unset the automatic or computed setting of a parameter and set the parameter to the current value. The ptrvalue field is ignored and can be set to NULL.

db2gCfg data structure specific parameters

dbname_len: Input. The length in bytes of dbname parameter.

db2gCfgParam data structure specific parameters

ptrvalue_len: Input. The length in bytes of ptrvalue parameter.

Usage notes

The configuration parameters maxagents and maxcagents are deprecated. In a future release, these configuration parameters may be removed completely.

The db2CfgSet API will tolerate updates to the maxagents and maxcagents configuration parameters, however these updates will be ignored by DB2.

Usage samples

CASE 1: The MAXAPPLS parameter will be set to 50 at dbpartitionnum 30.

CASE 2: The MAXAPPLS parameter will be set to 50 on all dbpartitionnum.

int updateDbConfig()
{
    struct sqlca sqlca = {0};
    db2Cfg cfgStruct = {0};
    db2CfgParam cfgParameters[2];
    char *dbAlias = "SAMPLE";

    /* initialize cfgParameters */
    cfgParameters[0].flags = 0;
    cfgParameters[0].token = SQLF_DBTN_TSM_OWNER;
    cfgParameters[0].ptrvalue = (char *)malloc(sizeof(char) * 65);
    cfgParameters[1].flags = 0;
    cfgParameters[1].token = SQLF_DBTN_MAXAPPLS;
    cfgParameters[1].ptrvalue = (char *)malloc(sizeof(sqluint16));

    /* set two DB Config. fields  */
    strcpy(cfgParameters[0].ptrvalue, "tsm_owner");
    *(sqluint16 *)(cfgParameters[1].ptrvalue) = 50;
  
    /* initialize cfgStruct to update db cfg on single partition*/
    cfgStruct.numItems = 2;
    cfgStruct.paramArray = cfgParameters;
    cfgStruct.flags = db2CfgDatabase | db2CfgImmediate;
    cfgStruct.flags |= db2CfgSingleDbpartition;
    cfgStruct.dbname = dbAlias;
    cfgStruct.dbpartitionnum = 30;

    /* CASE 1: update database configuration */
    db2CfgSet(db2Version950, (void *)&cfgStruct, &sqlca);

    /* set cfgStruct to update db cfg on all db partitions */
    cfgStruct.flags &= ~db2CfgSingleDbpartition;

    /* CASE 2: update database configuration */
    db2CfgSet(db2Version950, (void *)&cfgStruct, &sqlca);
    ..............
}