Application programming requirements for high availability for connections from Java clients to Db2 for z/OS servers

Failover for automatic client reroute can be seamless or non-seamless. If failover for connections to Db2 for z/OS is not seamless, you need to add code to account for the errors that are returned when failover occurs.

Before version 4.32 of the IBM® Data Server Driver for JDBC and SQLJ, if failover is not seamless, and a connection is reestablished with the data server, SQLCODE -30108 is returned to the application. All work that occurred within the current transaction is rolled back. In the application, you need to:
  • Check the reason code that is returned with the -30108 error to determine whether special register settings that were carried over from the failing data sharing member to the new (failover) data sharing member were the settings at the most recent commit point, or the settings at the point of failure. Reset any special register values that are not current.
  • Execute all SQL operations that occurred since the previous commit operation.

For seamless failover to occur, the following conditions must be satisfied for direct connections to Db2 for z/OS:

  • The application language is Java, CLI, or .NET.
  • The connection is not in a transaction. That is, the failure occurs when the first SQL statement in the transaction is executed.
  • The data server allows transport reuse at the end of the previous transaction. An exception to this condition is if transport reuse is not granted because the application was bound with KEEPDYNAMIC(YES).
  • All global session data is closed or dropped.
  • There are no open, held cursors.
  • If the application uses CLI, the application cannot perform actions that require the driver to maintain a history of previously called APIs in order to replay the SQL statement. Examples of such actions are specifying data at execution time, performing compound SQL, or using array input.
  • The application is not a stored procedure.
  • The application is not running in a Federated environment.
  • Two-phase commit is used, if transactions are dependent on the success of previous transactions. When a failure occurs during a commit operation, the client has no information about whether work was committed or rolled back at the server. If each transaction is dependent on the success of the previous transaction, use two-phase commit. Two-phase commit requires the use of XA support.

Seamless failover is attempted once. If a data sharing member on which seamless failover is attempted goes down, failover to another data sharing member is non-seamless.

During an attempt at seamless failover, the IBM Data Server Driver for JDBC and SQLJ returns an SQL error to the calling application in situations such as the following ones:

  • The target Db2 for z/OS data server is down.
  • If the connection request to the target Db2 for z/OS data server is processed, the MAXDBAT subsystem parameter value will be exceeded. MAXDBAT specifies the maximum number of concurrent active threads from remote locations to the data server.
  • If the connection request to the target Db2 for z/OS data server is processed, the exception threshold for the MONITOR THREADS keyword in the DSN_PROFILE_ATTRIBUTES table will be exceeded.

The SQL error that is returned depends on the version of the IBM Data Server Driver for JDBC and SQLJ:

  • Starting with version 4.32 of the IBM Data Server Driver for JDBC and SQLJ, if the connection to the data server is dropped, and the automatic client reroute feature fails to execute an SQL statement:
    • If IBM Data Server Driver for JDBC and SQLJ property enableSeamlessFailoverErrorCodes is not set or is set to false, the statement receives SQL error -4499.
    • If IBM Data Server Driver for JDBC and SQLJ property enableSeamlessFailoverErrorCodes is set to true, the statement receives SQL error -20542.
  • Before version 4.32 of the IBM Data Server Driver for JDBC and SQLJ, if the connection to the data server is dropped, and the automatic client reroute feature fails to execute an SQL statement, the statement receives SQL error -20542.

If multiple SQL errors occur, the underlying cause might be server-side abends or errors. The Db2 for z/OS administrator needs to investigate those abends or errors.