Updating VisibilityAPI Oracle Driver ( z/OS )

This article describes how to update the Oracle driver for VisibilityAPI on the z/OS platform

Please note, the patched driver detailed within this article requires the use of either Java 7 or Java 8

By default, VisibilityAPI is packaged with both "ojdbc6.jar" and "ojdbc14.jar" drivers. Utilizing an Oracle driver not supplied by Infogix will result with the following ERROR due to limitations with the driver ( api.log excerpt ) :

ERROR - main com.infogix.insight.insightapi.writer.db.DatabaseWriterService getDbConnection
java.sql.SQLRecoverableException: IO Error: Undefined Error
 at oracle.jdbc.driver.T4CConnection.logon(T4CConnection.java:673)
 at oracle.jdbc.driver.PhysicalConnection.<init>(PhysicalConnection.java:711)
 at oracle.jdbc.driver.T4CConnection.<init>(T4CConnection.java:385)
 at oracle.jdbc.driver.T4CDriverExtension.getConnection(T4CDriverExtension.java:30)
 at oracle.jdbc.driver.OracleDriver.connect(OracleDriver.java:558)
 at java.sql.DriverManager.getConnection(DriverManager.java:675)
 at java.sql.DriverManager.getConnection(DriverManager.java:258)
 at com.infogix.insight.insightapi.writer.db.DatabaseWriterService.getDbConnection(DatabaseWriterService.java:167)
 at com.infogix.insight.insightapi.writer.WriterFactory.createWriter(WriterFactory.java:81)
 at com.infogix.insight.insightapi.InsightAPIService.publishMessage(InsightAPIService.java:719)
 at com.infogix.insight.insightapi.InsightAPIService.createStartRecord(InsightAPIService.java:108)
 at com.infogix.insight.insightapi.ACRRecordParser.parse(ACRRecordParser.java:336)
 at com.infogix.insight.insightapi.ACRRecordParser.main(ACRRecordParser.java:538)
Caused by: oracle.net.ns.NetException: Undefined Error
 at oracle.net.ns.NSProtocolStream.negotiateConnection(NSProtocolStream.java:272)
 at oracle.net.ns.NSProtocol.connect(NSProtocol.java:263)
 at oracle.jdbc.driver.T4CConnection.connect(T4CConnection.java:1360)
 at oracle.jdbc.driver.T4CConnection.logon(T4CConnection.java:486)
 ... 12 more

If the need arises, these may be replaced with newer versions, though certain steps must be taken to ensure :

1 ) New driver is compatible with VisibilityAPI on z/OS

2 ) New driver has been reflected in all necessary locations of the VisibilityAPI installation

In this exercise, we will update an "ojdbc7" driver to allow compatibility with VisibilityAPI. The "ojdbc7.jar" driver may be downloaded from Oracle's website. It is encouraged to verify that you are downloading the latest version of the necessary driver.

Once the "ojdbc7.jar" has been downloaded, the following patch will be necessary to ensure compatibility with the z/OS platform ( and therefore VisibilityAPI ) :

https://support.oracle.com/knowledge/Middleware/2219003_1.html#FIX

Failure to update the driver with this patch will result in the following ( api.log excerpt ) :

ERROR - main com.infogix.insight.insightapi.writer.db.DatabaseWriterService getDbConnection
java.sql.SQLException: ORA-28040: No matching authentication protocol

at oracle.jdbc.driver.DatabaseError.throwSqlException(DatabaseError.java:125)
 at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:305)
 at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:272)
 at oracle.jdbc.driver.T4CTTIoauthenticate.receiveOsesskey(T4CTTIoauthenticate.java:243)
 at oracle.jdbc.driver.T4CConnection.logon(T4CConnection.java:304)
 at oracle.jdbc.driver.PhysicalConnection.<init>(PhysicalConnection.java:348)
 at oracle.jdbc.driver.T4CConnection.<init>(T4CConnection.java:151)
 at oracle.jdbc.driver.T4CDriverExtension.getConnection(T4CDriverExtension.java:32)
 at oracle.jdbc.driver.OracleDriver.connect(OracleDriver.java:563)
 at java.sql.DriverManager.getConnection(DriverManager.java:419)
 at java.sql.DriverManager.getConnection(DriverManager.java:467)
 at com.infogix.insight.insightapi.writer.db.DatabaseWriterService.getDbConnection(DatabaseWriterService.java:167)
 at com.infogix.insight.insightapi.writer.WriterFactory.createWriter(WriterFactory.java:81)
 at com.infogix.insight.insightapi.InsightAPIService.publishMessage(InsightAPIService.java:719)
 at com.infogix.insight.insightapi.InsightAPIService.createEndRecord(InsightAPIService.java:263)
 at com.infogix.insight.insightapi.ACRRecordParser.parse(ACRRecordParser.java:369)
 at com.infogix.insight.insightapi.ACRRecordParser.main(ACRRecordParser.java:538)

Attached to this article is an already updated "ojdbc7.jar" for reference. The attached driver was downloaded and patched on 11/2019, so it should be noted that newer versions of this driver may be available since the publication of this article.

Now that we have a compatible / updated version of the needed driver, we will place on the mainframe ( via binary transfer ) and ensure the following files have been updated to point accordingly :

1 ) ENVFILE / PROCLIB ( ENVSHELL )

This file will be located on the ISPF-side of the z/OS environment. Within, you will want to ensure to update the "CLASSPATH=" value to reflect the location of your new driver. In addition, updates to your Java LIBPATH / PATH may be necessary depending on what driver version is being utilized.

2 ) "recover.sh"

This file will be located on the USS-side of the z/OS environment ( <install_home/bin directory ). Within, you will want to ensure again that the "CLASSPATH=" value is reflecting the location of your new driver. In addition, updates to the Java being utilized may be performed.

Once all the above has been thoroughly updated, review the JCL for your job to reflect any necessary value changes ( JVMLDM70, new PROC, etc.. ).