While upgrading GoldenGate to 26ai for a DB2 z/OS source, I had to update the IBM Data Server Driver for ODBC and CLI (CLI Driver, in short) alongside it. Since I realized that DB2 driver know-how was rare in companies, I figured it would be worth writing a blog about the topic.

In this GoldenGate upgrade, the previous driver was version 11.1 and the target version was 12.1. After installing the new driver, db2cli execsql commands that previously worked started failing with the following error:

db2cli execsql -db <database_alias> -user <username> -passwd <password> \
  -inputsql /home/oracle/input.sql

Where /home/oracle/input.sql just contains a trivial test query:

select 1 from sysibm.sysdummy1;

The sysibm.sysdummy1 table is DB2’s equivalent of Oracle’s DUAL, so this is about the simplest query you can run to check connectivity. It failed with the following error:

SQLError: 1 = 0 (SQL_SUCCESS)
SQLGetDiagRec: SQLState : 42968
NativeError : -1598
DiagMsg: [IBM][CLI Driver] SQL1598N An attempt to connect to the database server failed because of a licensing problem. SQLSTATE=42968

What SQL1598N means

SQL1598N means the DB2 client does not have a valid license to connect to this database. The CLI driver loaded fine. But when it tried to establish an authenticated connection the server rejected it on licensing grounds.

This is distinct from a connection failure or an authentication failure.

Root cause

It might not be obvious for Oracle-accustomed DBAs, but the DB2 CLI Driver does not ship with a license file for connecting to DB2 for z/OS. A separate license file named db2consv_zs.lic must be placed manually in the clidriver/license/ directory of the driver installation.

The critical point is that the license file is version-specific and cannot be reused across driver versions. The license file that worked with driver 11.1 is not valid for driver 12.1. After upgrading the driver, the new installation directory does not contain the license file in the license/ folder, and copying the old license file into it will not resolve the error.

Observed behavior

The error was reproducible every time the same command was run against the new driver. For reference, a successful run against a properly licensed driver returns:

FetchAll: Columns: 1
1
1
FetchAll: 1 rows fetched.

License file location

It is important to keep in mind that the license file belongs in the license/ subdirectory of the CLI driver installation. With CLI driver 11.1, the path looked like:

/opt/ibm/db2_odbc_cli_11_1/clidriver/license/db2consv_zs.lic

After upgrading to 12.1, the new driver has its own separate installation directory with its own license/ subdirectory. Placing the old 11.1 license file there will not work – the file is tied to the driver version.

How to fix the issue ?

Since the old file is unusable, you must obtain a new license file matching the installed driver version from IBM. Essentially, you have two options here:

  • Contact your DB2 engineers: if someone on the team manages IBM software licenses, they should be able to provide the correct db2consv_zs.lic for the version you installed.
  • Open a case with IBM customer support: IBM will provide the appropriate license file for the new driver version.

Once you have the correct file, place it in the clidriver/license/ directory of the new driver installation and retry the same db2cli execsql command given above. No restart is required.

DB2 CLI drivers are not that complicated to use and to debug. However, there are a few fundamentals that GoldenGate administrators should know before attempting a migration. Renewing the license file is one of them.

Post Views: 1
Thumbnail [60x60]
by
Julien Delattre