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;
db2AutoConfigMembers iMembers;
} db2AutoConfigInterface;



typedef struct {
  char * pName;
  db2int32 value;
  db2int32 automatic;
  char reserved[8];
} db2AutoConfigBpElement;

typedef struct {
        db2Uint32 numElements;
        db2AutoConfigBpElement* pElements;
      } db2AutoConfigBpValues; 

typedef struct {
   db2Uint32 numElements;
   SQLZ_PDB_NODE_TYPE *pMemberNumber;
 } db2AutoConfigMemberArray;

typedef db2AutoConfigMemberArray db2AutoConfigMembers;

typedef struct {
   db2Uint32  numElements;
   db2ConfigValues *oOldDbValues;
   db2ConfigValues *oNewDbValues;

   db2AutoConfigBpValues  *oOldBpValues;
   db2AutoConfigBpValues  *oNewBpValues;
   db2AutoConfigDiags *oDiagnostics;

   SQLZ_PDB_NODE_TYPE *pMemberNumber;
 } db2AutoConfigMemberValuesArray;

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  db2AutoConfigOutput {
   db2ConfigValues  oOldDbValues;   
   db2ConfigValues  oOldDbmValues;
   db2ConfigValues  oNewDbValues;  
   db2ConfigValues  oNewDbmValues;
   db2AutoConfigDiags  oDiagnostics;
   db2BpValues  oOldBpValues;
   db2BpValues  oNewBpValues;  
   db2WAValues oOldWAValues;
   db2WAValues oNewWAValues;   
   db2WASValues oOldWASValues;
   db2WASValues oNewWASValues;   
   db2WCSValues oOldWCSValues;
   db2WCSValues oNewWCSValues;
   db2ThreshConcurValues oOldThreshConcur;   
   db2ThreshConcurValues oNewThreshConcur;

   db2AutoConfigMemberValuesArray oMemberValues;
 } db2AutoConfigOutput;

db2AutoConfigBpElement data structure parameters

pName: Output. The name of the output buffer pool.
value: Output. Hold the size (in pages) of the buffer pool specified in the name.
automatic: Output. A non-zero values indicates the buffer pool specified in the name is automatic.
reserved: Output. Reserved for future use.

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.

iMembers

Input. Passes the member numbers to report on.

iParams

Input. Passes parameters into the advisor.

oResult

Output. Includes all results from the advisor.

db2AutoConfigMemberArray data structure parameters

numElements: Input. The number of array elements.
memberNumber: Input. A pointer to the member number.

db2AutoConfigMemberValuesArray data structure parameters

numElements: Input or output. The number of array elements in each array below where each element belongs to a single member.
oOldDbValues: Output. If the iApply value is set to update the database configuration or all configurations, each elements represents the database configuration value prior to using the advisor on a member. Otherwise, this is the each elements represents the current value on a member.
oNewDbValues: Output. If the iApply value is set to update the database configuration or all configurations, each element represents the current database configuration value on a member. Otherwise, each element represents the recommended value for the advisor on a member.
oOldBpValues: Output. If the iApply value is set to update the database configuration or all configurations, each elements represents the buffer pool sizes in pages before using the advisor on a member. Otherwise, each element is the current value on a member.
oNewBpValues: Output. If the iApply value is set to update the database configuration or all configurations, each elements represents the current buffer pool sizes in page on a member. Otherwise, each element is the recommended value for the advisor on a member.
oDiagnostics: Output. Includes diagnostics from the advisor.
oMemberNumbers: Output. Member numbers for the elements contained within the arrays above.

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.

db2AutoConfigBpValues data structure parameters

numElements: Output. The number of array elements.
pElements: 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 on the coordinating member.
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 on the coordinating member. Otherwise, this is the recommended value for the advisor on the coordinating member.
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 on the coordinating member.
oNewBpValues: Output. If the iApply value is set to update the database configuration or all configurations, this value represents the current buffer pool sizes in pages on the coordinating member. Otherwise, this is the recommended value for the advisor on the coordinating member.
oMemberValues: Output. A db2AutoConfigMemberValuesArray structure containing the old and new database configuration parameter values, diagnostics, and bufferpool settings from the advisor on a per-member basis.

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.