{"id":46580,"date":"2026-08-27T08:17:00","date_gmt":"2026-08-27T06:17:00","guid":{"rendered":"https:\/\/www.dbi-services.com\/blog\/?p=46580"},"modified":"2026-08-23T21:17:47","modified_gmt":"2026-08-23T19:17:47","slug":"goldengate-db2-z-os-upgrade-checklist","status":"publish","type":"post","link":"https:\/\/www.dbi-services.com\/blog\/goldengate-db2-z-os-upgrade-checklist\/","title":{"rendered":"GoldenGate DB2 z\/OS Upgrade Checklist"},"content":{"rendered":"\n

Upgrading GoldenGate when the source is DB2 for z\/OS<\/strong> is not quite the same exercise as upgrading a GoldenGate installation for Oracle. Most of what I described in my generic blogs about planning a GoldenGate upgrade<\/a> and migrating from Classic to Microservices Architecture<\/a> is still valid. However, there is an extra layer to deal with. It has to do with the IBM Data Server Driver for ODBC and CLI<\/strong>, and everything DB2-side depending on it. This blog is a consolidated checklist of everything you should check before, during, and after a GoldenGate for DB2 z\/OS upgrade, based on issues I faced.<\/p>\n\n\n\n

Why DB2 z\/OS upgrades are different<\/h2>\n\n\n\n

With Oracle, a GoldenGate upgrade does not really involve the databases themselves. You just have to install the new home, and migrate or reconfigure extracts and replicats. Provided that you do not have a complex custom layer on top of it (automation, pipelines, etc.), this is everything you have to do. With DB2 z\/OS, GoldenGate talks to the DB2 database through the CLI driver<\/strong>. This driver has its own version, its own licensing, and its own DB2-side procedures that need to be updated. If you only upgrade GoldenGate and the CLI driver but forget the DB2 z\/OS side, you will hit errors when trying to extract data from DB2. On top of this, a stored procedure is installed in the DB2 database, for GoldenGate to work.<\/p>\n\n\n\n

The SQL1598N<\/code> licensing issue<\/h2>\n\n\n\n

The first error you might encounter when upgrading the CLI driver as part of a GoldenGate upgrade is related to the licensing file. I detailed this in a previous blog<\/a>, but the short version is: the IBM Data Server Driver for ODBC and CLI does not ship with a license file to connect to DB2 for z\/OS. A separate file, db2consv_zs.lic<\/code>, has to be placed manually into the clidriver\/license\/<\/code> directory. This file is tied to the exact driver version<\/strong> ! Reusing the license from your old driver (11.1<\/code>) in the new driver\u2019s directory (12.1<\/code>) will not work, and connections will fail with:<\/p>\n\n\n\n

SQLState : 42968\nNativeError : -1598\nDiagMsg: [IBM][CLI Driver] SQL1598N An attempt to connect to the database\nserver failed because of a licensing problem. SQLSTATE=42968<\/code><\/pre>\n\n\n\n
Remember to get the new license file and test it way before the cutover. Whoever manages IBM software on your side, or IBM support directly, needs to provide a new<\/strong> db2consv_zs.lic<\/code> matching the target driver version. Since getting a license file from IBM support is rarely instantaneous, plan some time to get this done.<\/p>\n\n\n\n
The DB2-side stored procedure step<\/h2>\n\n\n\n
This is the part which is easy to miss because it doesn\u2019t happen on the GoldenGate host at all. However, it is documented by Oracle. A GoldenGate extract for DB2 z\/OS relies on an initialization and utility stored procedure<\/strong> which is installed directly in DB2 itself. This stored procedure ships with each GoldenGate release and is versioned against it. When you upgrade GoldenGate, the stored procedure sitting in the DB2 subsystem does not upgrade itself. It stays at whatever version was installed during the last GoldenGate install, until it is explicitly reinstalled.<\/p>\n\n\n\n
When setting up a new GoldenGate home for DB2, a zOSutils.zip<\/code> file is included under $OGG_HOME\/lib<\/code>. This is what you must use. The new stored procedure will replace the old one in the catalog.<\/p>\n\n\n\n
Just like the CLI driver issues described above, this should be managed by DB2 engineers<\/strong>. Installing or replacing a stored procedure at the DB2 level requires the appropriate privileges, which a Database\/GoldenGate\/Linux administrator typically does not have. Talk with your DB2 for z\/OS DBA or systems engineer<\/strong> as part of the upgrade plan, and treat the stored procedure reinstall as a mandatory step of the GoldenGate upgrade itself.<\/p>\n\n\n\n
OGG-30121<\/code> or OGG-30057<\/code> with DB2 procedure upgrade<\/h3>\n\n\n\n
If GoldenGate itself gets upgraded but the stored procedure in the DB2 subsystem is left at its old version, the extract will detect the mismatch at startup and abend with OGG-30121<\/code>:<\/p>\n\n\n\n
OGG-30121  ERROR  The initialization and utility stored procedure major version is 210610 and is not compatible with this Extract. (The minor version is 00).<\/code><\/pre>\n\n\n\n
Getting an OGG-30121<\/code> error during a GoldenGate upgrade means that the DB2-side stored procedure reinstall was missed. There is no need to start debugging the GoldenGate configuration.<\/p>\n\n\n\n
Also, please note that this stored procedure change needs to happen during the GoldenGate upgrade, not before. What I mean by this is that you cannot ask for the stored procedure to be updated a week before the GoldenGate upgrade. You will need to allocate time for updating the stored procedure<\/strong> in your upgrade scenario.<\/p>\n\n\n\n
The reverse situation also exists. If you update the procedure but not GoldenGate, you will have an OGG-30057<\/code> error when attempting to restart the extracts.<\/p>\n\n\n\n
OGG-30057  ERROR  The log reading user-defined function major version is 231010 and is not supported. (The minor version is 00)<\/code><\/pre>\n\n\n\n
Other things to check during the upgrade<\/h2>\n\n\n\n
Here are a few other points regarding issues I faced when upgrading GoldenGate for DB2 setups in the past:<\/p>\n\n\n\n