Technote (troubleshooting)
Problem(Abstract)
A DB2 .NET application may receive an exception as follows:
SQL1159 Initialization error with DB2 .NET Data Provider, reason code 10, tokens 0.0.0, 9.5.3
Cause
An SQL1159 error may be returned if the DB2 .NET data provider had a problem during initialization.
When the DB2 .NET data provider is initialized it will perform some checks to ensure that the DB2 .NET data provider can be used properly. One of those checks is to see if it can execute a function from within the DB2 native client library called db2app.dll, and before that can be done it tries to load the db2app.dll library in memory.
Several different reason codes can be returned with the SQL1159 exception, but reason code 10 occurs when there is a mismatch between the DB2 native client library (db2app.dll) and the DB2 .NET data provider library (IBM.Data.DB2.dll).
SQL1159 reason code 10 will return two tokens. The first token is the version of the DB2 client library, and the second token is the version of the DB2 .NET data provider.
If the version of the DB2 client library is returned as 0.0.0, then that means that there was a problem during the initialization of the db2app.dll library.
There are potentially two reasons why a token of 0.0.0 is returned for the native DB2 client library.
The first is that the db2app.dll is not compatible with the version of the DB2 client that is installed. The second is that there was a permission problem when trying to use the db2app.dll library with the application process.
Resolving the problem
Incompatible db2app.dll version
Every DB2 fixpak and release has its own version of the db2app.dll library. The file size and signature will be different for each fixpak and release. It is very important that when DB2 is installed that the db2app.dll library is the one that came from that level of DB2 that is being installed.
DB2 will update the db2app.dll library during the install of a fixpak or during the migration from one release to another. If there was a problem updating the db2app.dll, DB2 will document that in its installation log file.
Here is an example of a typical error in the DB2 install log when the db2app.dll could not be updated:
InstallFiles: File: db2app.dll, Directory: C:\Program Files\IBM\SQLLIB\BIN\, Size: 9680160
Info 1603.The file C:\Program Files\IBM\SQLLIB\BIN\db2app.dll is being held in use. Close that application and retry.
MSI (s) (CC:B0) [11:18:48:389]: Product: DB2 Connect Server - DB2COPY1. The file C:\Program Files\IBM\SQLLIB\BIN\db2app.dll is being held in use by the following process Name: msiexec , Id 5392.
If this was the case, then it is important that all applications were shut down before upgrading DB2. This includes any applications that run as Windows services, such as an application server that might be making DB2 connections. The above error is a result of an application holding a lock on the db2app.dll file, thus disallowing DB2 from updating the file.
To verify that the db2app.dll library is in fact compatible with the DB2 level, issue the db2level command, and then compare the level with the file version of the db2app.dll. To retrieve the file version, find the db2app.dll using Windows Explorer and right-click on it and go to Properties->Version.
Invalid priviliges
When the db2app.dll library is initialized by the DB2 .NET data provider, it initializes an application environment. This process will ensure that the db2app.dll library can be used. Some of the things it does is it checks to see what DB2 environment variables are set, and it checks things like the client-side database manager configuration file. If the DB2 .NET data provider could not initialize the application environment properly then DB2 .NET will return 0.0.0 for the native DB2 client library version.
The most common reason why the initialization of the application environment fails is because of invalid privileges. And the most common reason why there are invalid privileges is if DB2 Extended Security is enabled, and the userid that the application process runs under is not a member of either the DB2ADMNS or the DB2USERS groups.
If DB2 Extended Security is enabled (this is the default behavior for DB2 installations), then it is mandatory that any DB2 'user' belongs to either the DB2ADMNS or the DB2USERS group. This is not just the userid that is used during authentication with DB2, but it also includes the owner of the application process.
Some application processes like the w3wp.exe process (which is a process used by Microsoft Information Integrator (IIS)) can run under a different userid than the one that connects to DB2. It is important that this user belongs to the proper DB2 Extended Security group, if DB2 Extended Security is enabled.
If running IIS 7, the default account used for anonymous access is called "IUSR". This user can be added to the extended security group to resolve this error.
To determine what userid is actually trying to use the .NET application then you can use a utility called the Microsoft® Process Monitor located here:
That utility will track all file and registry operations issued by any Windows process. If that process failed to read a file, then it will record an ACCESS DENIED error. Microsoft® Process Monitor can show who the userid was that tried to access the file when it failed. Adding that userid to the proper DB2 Extended Security group should then resolve that problem. The userid that is used by the application can be impersonated by another userid. Microsoft® Process Monitor will show who the Impersonating userid is, and that is the userid that needs to be added to the proper DB2 Extended Security group.
If DB2 Extended Security is enabled, and the preference is to not use DB2 Extended Security, then the ideal thing to do would be to uninstall DB2 and reinstall it without the DB2 Extended Security option.
If Microsoft Windows® 7 or Microsoft Windows Vista® are being used, and DB2 Extended Security is disabled, the problem may still occur due to invalid privileges, specifically if the userid that installed DB2 was not given elevated administrator rights. Typically when User Account Control (UAC) is enabled, users with administrator rights run with least user privileges. These rights can be elevated to perform administrative tasks. If a non-elevated administrator installed DB2 then certain Windows registry settings used by DB2 may not be set properly, preventing the DB2 .NET data provider from working properly. It is important to ensure that a userid with elevated administrator privileges has installed DB2 to resolve this problem.
If using the IBM Data Server Driver Package, then you could also get this error if you were hitting APAR JR30952 (that is fixed in DB2 v9.5 FP5) or APAR IC63971 (that is fixed in DB2 v9.7 FP1). DB2 Extended Security was being enabled implicitly for the IBM Data Server Driver when it should not have been, and that would result in this error since DB2 would think that the userid running the application would not be a member in the proper DB2 Extended Security group.