Interpreting Vendor API return codes from db2diag.log messages

If we follow the function sequence we see the following:

sqlpgArchiveLogFile -> sqlpgArchiveLogVendor -> sqlpInitVendorDevice

We see that sqlpInitDevice has a return code (RETCODE) of ZRC=0x0000000B=11

ZRC codes are set by DB2 functions, so 11 must be a DB2 return code.

The definitions for all DB2 to Vendor API return codes are found under the instance home directory <sqllib>/include/ in the sqluvend.h header file.

The above return code is in this example:

#define SQLUV_INIT_FAILED      11  /* Initialization failed */

Similarly one can find the meaning of other DB2 to Vendor API return codes, in this way.

Note, however, that this return code is not the return code from the Vendor API. To find this out we must at the very first instance of the db2diag.log message, in the above group of diagnostic messages:

2006-08-29-23.36.45.181336-240 I171851309A565 LEVEL: Error
PID : 1287366 TID : 1 PROC : db2logmgr (DBNAME) 0
INSTANCE: db2inst1  NODE : 000
FUNCTION: DB2 UDB, data protection, sqlpInitVendorDevice, probe:1030
MESSAGE : sqluvint failed! Vendor rc:
DATA #1 : Hexdump, 48 bytes
0x0FFFFFFFFFFFD120 : 0000 01AA 3432 3520 3432 3600 0000 0000 ....425 426.....
0x0FFFFFFFFFFFD130 : 0000 0000 0000 0000 0000 0000 0000 0000 ................
0x0FFFFFFFFFFFD140 : 0000 0000 0000 0000 0000 0000 0000 0000 ................

The Vendor rc is defined to of type Return_code which is defined in <sqllib>/include/sqluvend.h as:

#define SQLUV_COMMENT_LEN     30

typedef struct Return_code
{
        sqlint32   return_code;  /* return code from the vendor function  */
        char       description[SQLUV_COMMENT_LEN];
        /* descriptive message                   */
        void       *reserve;     /* reserve for future use                */
} Return_code;

This structure is dumped out in the DATA component of the above diagnostic entry:

DATA #1 : Hexdump, 48 bytes

0x0FFFFFFFFFFFD120 : 0000 01AA 3432 3520 3432 3600 0000 0000 ....425 426.....
0x0FFFFFFFFFFFD130 : 0000 0000 0000 0000 0000 0000 0000 0000 ................
0x0FFFFFFFFFFFD140 : 0000 0000 0000 0000 0000 0000 0000 0000 ................

sqlint32 takes up 4 bytes, so the return code from the vendor function is to be found in the first 4 bytes of the above diagnotics data entry. This is hexadecimal dump (hexdump).

So, in the above case we see that the value is hex 0000 01AA which is corresponds to decimal 426.
Note: the value for the description array is
3432 3520 3432 3600 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000
which happens to contain the return code value. We should not rely soley on the description array though.

Now that we have the Vendor's return code one can find out what that means by simply looking up the Vendor API documentation. In the case of TSM one can find this here:

http://publib.boulder.ibm.com/infocenter/tivihelp/v1r1/topic/com.ibm.itsmm.doc_5.4/anrcms589408.htm

A quick search for 426 we see

#define DSM_RC_CANNOT_OPEN_TRACEFILE 426/* cannot open trace file  */

Now, if the above DATA component contains all zeros and the db2diag.log contains a number of signal handler diagnostic entries, then it is likely that an abnormal termination has occurred in the vendor's library.

In this case you would see a rc = 30 in the sqlpgArchiveLogFile function.

This DB2 return code is defined in the sqluvend.h file as:

#define SQLUV_UNEXPECTED_ERROR 30 /* A severe error was experienced */