By: Rajib Sarkar (rssarkar)
STSM Db2 Support

July 5, 2017

Although this command shares the name of its more famous cousin "db2pd" it sits at a pecking order far below db2pd. I've rarely seen customers use it and some of them are even unaware of it ( granted we are not so good at publicizing :-) ). My blog is more performance centric but once in a while I do take a detour and try and introduce something new to the readers, today being one of them. 

So, there are quite a few things you can accomplish using db2pdcfg and some of them are documented and some of them are undocumented. Some of the undocumented ones are downright dangerous if not used with proper guidance so I'll not list them here :-). However, there are quite a few options which I've found very useful and have used for several customer issues. I should state one fact, the changes or settings you implement using this command does NOT survive a recycle of the instance. If there is a setting you want permanently, there are regvars ( if there is an equivalent )  which can be used to make it permanent. You can see the available sub-commands using db2pdcfg -h. If you issue just the db2pdcfg command 

Following is a list of useful commands for db2pdcfg.

-catch

If you have a situation, where a sqlcode error is being thrown but you are not able to get the required data right when it happens, this command can help you. You can set it to trigger data capture based on

1. a SQLCODE or
2. SQLCODE,Reason code or
3. ZRC ( seen in db2diag.log, however you will have to pass the integer value here ) number or
4. ADM errors or
5. a string appearing in db2diag.log or
6. just passing a string "locktimeout" or "deadlock". 

Syntax:

 -catch clear | status | <errorCode> [<action>] [count=<count>]

(Default action: Produce stack trace in db2diag.log, Run ~/sqllib/bin/db2cos script ). 

The count suboption controls how many times you want -catch to trigger data collection when the errorcode is hit. Typically count=1 is preferred so as to not fill up DIAGPATH file system. 

Some outliers

In the <action> sub-section there are many possibilities, one of them being stopdb2trc. This helps if you have db2trc running but would like to stop when the error is hit. Another one is if there is a specific lockname you want to trigger data capture, you can pick up the large hex value printed in db2pd -locks output and stick it in as "lockname=<hex val>" and it will trigger only when the lockname is hit. 

Some examples of typical usage I have used on customer systems :

1) Trigger data capture based on SQL error -911,2 ( deadlock ):

db2pdcfg -catch -911,2 count=1

2) Trigger data capture based on SQL error -1224 on a DPF system

db2_all "db2pdcfg -catch -1224 count=1" 

3) Trigger data capture based on a diaglog string

db2pdcfg -catch diagstr="ENOMEM" count=1

You can specify multiple catch options one after the other and they will trigger whenever one is hit. 

In order to check on what conditions you have set the catch for:

db2pdcfg -catch status

In order to clear the catch conditions:

db2pdcfg -catch clear

-cos

By default, the db2cos is set to trigger data collection for specific events such as traps etc. However, there can be times that you want to stop it from doing it as it is filling up the DIAGPATH file system and you just want to temporarily turn it off. You can use this option to accomplish that.

Syntax:

db2pdcfg -cos [status] [off] [on] [sleep=<numsec>] [timeout=<numsec>] [count=<count>] [SQLO_SIG_DUMP]

Some examples:

1) To turn off db2cos trigger 

db2pdcfg -cos off

2) To reduce the timeout  for invocation of db2cos script ( pls. keep in mind, when db2cos script is invoked the agent invoking it actually waits for the script to finish before proceeding )

db2pdcfg -cos sleep=10 ( default is 300 seconds ). 

Sometimes, db2cos script commands can get stuck and the default timeout can actually hurt the performance of an agent. This is where this option helps.

-diaglevel

This option although undocumented, can be very useful in some cases. This was introduced recently so 10.5fp6+, 11.1GA+ onwards have it. This can be used to control the messaging of different components at what DIAGLEVEL. Typically, all components within DB2 adhere to the default DIAGLEVEL of 3 but say a situation appears where you can see the instance db2diag.log is being spammed with some message of a specific component ( the function name -- first 4 letters -- has the component the message belongs to ). You can then use this option to direct the component to dump messages only for say a lower level ( maybe 0 or 1 ) i.e. only Severe errors. 

1) To see the current diaglevel of the components

db2pdcfg -diaglevel

2) To set a specific diaglevel for a component

db2pdcfg -diaglevel SQLD=2

Pls. keep in mind that this is a temporary workaround as a permanent fix can come from DB2 support/dev only, so pls. open up a PMR to report the issue.

-fodc

This option can be used to control the core file dumping behaviour, for example, a different directory than the default, size of the core, turning on/off dumping core. The most typical use I've seen is to redirect the core dump to a dir with enough space to avoid filling up DIAGPATH. 

Syntax:

-fodc [status] [reset] [DUMPCORE=<ON,OFF,AUTO>] [DUMPDIR=<directory>] [CORELIMIT=<numK|M|G >bytes] [SERVICELEVEL=<BASIC,FULL,AUTOMATIC>]

Some usage examples:

1) To change the default directory to dump core

db2pdcfg -fodc DUMPDIR=<dir> 

If you want to make it permanent, you will have to use the registry var DB2FODC and then set the DUMPDIR there. 

2) To turn off dumping core

db2pdcfg -fodc DUMPCORE=OFF

These are some of the options which are used fairly frequently on the field and we ( being DB2 support ) haven't heard of any complaints, so I would deem them fairly safe to use. 

Hope you find them useful !