DB2 Version 10.1 for Linux, UNIX, and Windows

db2AutoConfig API - Access the Configuration Advisor

Allows application programs to access the Configuration Advisor.

Scope

In a partitioned database environment, database recommendations are applied by default on all database partitions. DB2_SG_APPLY_ON_ONE_NODE flag for the db2AutoConfigInterface data structure's iApply parameter forces the changes to be limited to the coordinator partition only. Note that the bufferpool changes are always (DB2_SG_APPLY_ON_ONE_NODE does not matter for bufferpool recommendations) applied to the system catalogs, thus, all database partitions are affected.

Authorization

SYSADM

Required connection

Database

API include file

db2AuCfg.h

API and data structure syntax

SQL_API_RC SQL_API_FN
db2AutoConfig(
  db2Uint32 db2VersionNumber,
  void * pAutoConfigInterface,
  struct sqlca * pSqlca);

typedef struct {
  db2int32 iProductID;
  char iProductVersion[DB2_SG_PROD_VERSION_SIZE+1];
  char iDbAlias[SQL_ALIAS_SZ+1];
  db2int32 iApply;
  db2AutoConfigInput iParams;
  db2AutoConfigOutput oResult;
} db2AutoConfigInterface;

typedef struct {
  db2int32 token;
  db2int32 value;
} db2AutoConfigElement;

typedef struct {
  db2Uint32 numElements;
  db2AutoConfigElement *  pElements;
} db2AutoConfigArray;
typedef db2AutoConfigArray  db2AutoConfigInput;
typedef db2AutoConfigArray  db2AutoConfigDiags;

typedef struct {
  db2Uint32 numElements;
  struct db2CfgParam * pConfigs;
  void * pDataArea;
} db2ConfigValues;

typedef struct {
  char * pName;
  db2int32 value;
} db2AutoConfigNameElement;

typedef struct {
  db2Uint32 numElements;
  db2AutoConfigNameElement * pElements;
} db2AutoConfigNameArray;
typedef db2AutoConfigNameArray db2BpValues;

typedef struct { 
  db2ConfigValues oOldDbValues;
  db2ConfigValues oOldDbmValues;
  db2ConfigValues oNewDbValues;
  db2ConfigValues oNewDbmValues;
  db2AutoConfigDiags oDiagnostics;
  db2BpValues oOldBpValues;
  db2BpValues oNewBpValues;
} db2AutoConfigOutput;

db2AutoConfig API parameters

db2VersionNumber: Input. Specifies the version and release level of the structure passed in as the second parameter, pAutoConfigInterface.
pAutoConfigInterface: Input. A pointer to the db2AutoConfigInterface structure.
pSqlca: Output. A pointer to the sqlca structure.

db2AutoConfigInterface data structure parameters

iProductID

Input. Specifies a unique product identifier. Valid values for the iProductID parameter (defined in db2AuCfg.h, located in the include directory) are:

DB2_SG_PID_DEFAULT
DB2_SG_PID_WEBSPHERE_COMMERCE_SUITE
DB2_SG_PID_SAP
DB2_SG_PID_WEBSPHERE_ADVANCED_SERVER
DB2_SG_PID_SIEBEL
DB2_SG_PID_PS_EPM
DB2_SG_PID_PS_ONLINE
DB2_SG_PID_PS_BATCH
DB2_SG_PID_PS
DB2_SG_PID_LOTUS_DOMINO
DB2_SG_PID_CONTENT_MANAGER

iProductVersion

Input. A 16 byte string specifying the product version.

iDbAlias

Input. A string specifying a database alias.

iApply

Input. Updates the configuration automatically. Valid values for the iApply parameter (defined in db2AuCfg.h, located in the include directory) are:

DB2_SG_NOT_APPLY: Do not apply any recommendations
DB2_SG_APPLY: Apply all recommendations
DB2_SG_APPLY_DB: Apply only database (and bufferpool) recommendations
DB2_SG_APPLY_ON_ONE_NODE: Apply database recommendations (valid only with DB2_SG_APPLY and DB2_SG_APPLY_DB) on the current database partition only. By default the database recommendations are applied on all database partitions.

iParams

Input. Passes parameters into the advisor.

oResult

Output. Includes all results from the advisor.

db2AutoConfigElement data structure parameters

token: Input or output. Specifies the configuration value for both the input parameters and the output diagnostics.
value: Input or output. Holds the data specified by the token.

db2AutoConfigArray data structure parameters

numElements: Input or output. The number of array elements.
pElements: Input or output. A pointer to the element array.

db2ConfigValues data structure parameters

numElements: Input or output. The number of array elements.
pConfigs: Input or output. A pointer to an array of db2CfgParam structure.
pDataArea: Input or output. A pointer to the data area containing the values of the configuration.

db2AutoConfigNameElement data structure parameters

pName: Output. The name of the output buffer pool.
value: Input or output. Holds the size (in pages) of the buffer pool specified in the name.

db2AutoConfigNameArray data structure parameters

numElements: Input or output. The number of array elements.
pElements: Input or output. A pointer to the element array.

db2AutoConfigOutput data structure parameters

oOldDbValues: Output. If the iApply value is set to update the database configuration or all configurations, this value represents the database configuration value before using the advisor. Otherwise, this is the current value.
oOldDbmValues: Output. If the iApply value is set to update all configurations, this value represents the database manager configuration value before using the advisor. Otherwise, this is the current value.
oNewDbValues: Output. If the iApply value is set to update the database configuration or all configurations, this value represents the current database configuration value. Otherwise, this is the recommended value for the advisor.
oNewDbmValues: Output. If the iApply value is set to update all configurations, this value represents the current database manager configuration value. Otherwise, this is the recommended value for the advisor.
oDiagnostics: Output. Includes diagnostics from the advisor.
oOldBpValues: Output. If the iApply value is set to update database configuration or all configurations, this value represents the buffer pool sizes in pages before using the advisor. Otherwise, this value is the current value.
oNewBpValues: Output. If the iApply value is set to update database configuration or all configurations, this value represents the current buffer pool sizes in pages. Otherwise, this is the recommended value for the advisor.

Usage notes

To free the memory allocated by the db2AutoConfig API, call the db2AutoConfigFreeMemory API.

With the deprecation of the maxagents and maxcagents configuration parameters, the behavior of the db2AutoConfig API will depend on the db2VersionNumber passed in to the API. If the version is DB2® v9.5 or beyond, maxagents will not be returned, but, for versions before this, it will. In a future release, these configuration parameters may be removed completely.