keepAliveTimeOut in IBM Data Server Driver for JDBC and SQLJ

Objective

1. Overview

The keepAliveTimeOut property is a TCP/IP-level configuration used in IBM Db2 JDBC (JCC) drivers to detect unresponsive or broken connections. It defines the maximum time (in seconds) before a connection is considered dead due to inactivity or failure in the TCP/IP layer.

Supported Only For:
IBM Data Server Driver for JDBC and SQLJ Type 4 connectivity.

2. Purpose and Importance

• High Availability: Enables faster detection of dead sockets, crucial for failover and recovery mechanisms like Automatic Client Reroute (ACR).
• Network Resilience: Helps applications gracefully handle network disruptions.
• Performance Optimization: Reduces latency in identifying broken connections, improving responsiveness.

3. Behavior of keepAliveTimeOut

The property controls:

• Delay before the first TCP keepalive probe.
• Interval between subsequent probes.
• Maximum time to conclude the peer is dead.

4. Mapping Logic

The driver translates keepAliveTimeOut into three TCP keepalive settings:

Mapping Rules:

If keepAliveTimeOut > 0 and ≤ 10:

    keepIdle = 1 second

    keepInterval = 1 second

    keepCount = keepAliveTimeOut

If keepAliveTimeOut > 10:

    keepIdle = keepAliveTimeOut / 3

    keepCount = 10

    keepInterval = max(((keepAliveTimeOut - keepIdle) / keepCount), 1)

If keepAliveTimeOut = 0:

    Driver defers to OS defaults

Example Calculation

For keepAliveTimeOut = 30 seconds:

keepIdle = 30 / 3 = 10s

keepCount = 10

keepInterval = max(((30 - 10) / 10), 1) = 2s

Result:

• keepIdle = 10s
• keepInterval = 2s
• keepCount = 10

5. Probe Behavior

• First probe after 10s of inactivity.
• Up to 10 probes, each 2s apart:

Probe 1: 10s

Probe 2: 12s

...

Probe 10: 28s

Connection declared dead at ~30s.

6. Configuration Options

a) Datasource Property

Java

DB2SimpleDataSource ds = new DB2SimpleDataSource();

ds.setKeepAliveTimeOut(20);

b) Connection URL

jdbc:db2://db2host:50000/MYDB:keepAliveTimeOut=20;

c) db2dsdriver.cfg

XML

<configuration>

<databases>

<database name="MYDB" host="db2host" port="50000">

<parameter name="keepAliveTimeout" value="20"/>

</database>

</databases>

</configuration>

7. Value Range and Defaults

• Default: 15 seconds
• Range: 0 to 32,767 seconds
• Data Type: int
• Value = 0: Uses OS defaults