Configuring automatic client reroute for applications that use Db2 databases

You can configure your client applications for a DB2® database to recover from a communication loss with the automatic client reroute (ACR) feature. The applications can continue to work with minimal interruption. The ACR feature is provided by the Db2 server and is not a feature of the application server.

Before you begin

This task assumes the following preconditions:
  • You have a Db2 data source that is defined in the application server. For more information about creating a data source, see the Configuring a data source by using the administrative console topic.
  • The Db2 data source to which your application connects is running one of the following Db2 versions:
    • Db2 for z/OS Version 10.1 or later
    • Db2 Database for Linux®, UNIX, and Windows Version 9.7 or later
  • You implemented the Db2 database with a redundant setup or the ability to fail the Db2 server to a standby node.
  • [z/OS]You are connecting to the data source with a Type-4 connection.

About this task

With the ACR feature for Db2, you can reroute to an alternative database server location if the connection to the primary database server fails. This feature is provided by the Db2 server and IBM Data Server Driver for JDBC and SQLJ (JCC) and is not a feature of the application server. You must enable and configure ACR on the Db2 server. For more information, see the Db2 Automatic client reroute documentation in Related Information.

After you configure ACR on the Db2 server, you must also configure the Db2 data source in the application server. To support client reroute, you must specify the alternative server name and alternative port number fields or the clientRerouteAlternateServerName and clientRerouteAlternatePortNumber data source custom properties. The values of these properties must match the values that are configured in the Db2 server. After ACR is configured, if the JDBC driver is not able to connect to the primary Db2 server, JCC reroutes the connection to the alternative server.

Attention: The data source custom property, enableClientAffinitiesList, changes the semantics of the clientRerouteAlternateServerName and clientRerouteAlternatePortNumber properties. To learn more about these properties, see the Db2 documentation topic, Common IBM Data Server Driver for JDBC and SQLJ properties for all supported database products. To learn more about client affinity, see the topic, Configuring client affinity for applications that use Db2 databases.

If you configured a Db2 data source as a Type 4 JDBC driver, you can use the Client reroute server list JNDI name field, or the clientRerouteServerListJNDIName data source custom property, to enable persistence of the client reroute state. Typically, when a connection is rerouted and the JDBC driver has connected to the alternative Db2 server, the alternative server sends information about its own alternative server to the JDBC driver. The JDBC driver then has the information that is required to reroute the connection again if the alternative Db2 server is not available. Effectively, the server that was originally the alternative server is now the primary server, and a new alternative server has been established. If you enable persistence for client reroute, this new state can be remembered. If the application server crashes and is restarted, the JDBC driver can connect to the Db2 server that was considered the primary server at the time of the crash. Without the persistence feature, the JDBC driver must start from the original server configuration and attempt to connect to the server that was originally considered the primary server.

Procedure

  1. In the administrative console, click Resources > JDBC > Data sources > data_source.
  2. Click WebSphere Application Server data source properties.
  3. In the Db2 automatic client reroute options section, complete the fields to enable client rerouting.
    Complete the following fields:
    Alternative server names
    Specifies the list of alternative server name or names for the Db2 server. If more than one alternative server name is specified, the names must be separated by commas. For example:
     host1,host2
    Alternative port numbers
    Specifies the list of alternative server port or ports for the Db2 server. If more than one alternative server port is specified, the ports must be separated by commas. For example: 
    5000,50001
    Avoid trouble: Ensure that an equal number of entries must be specified for both alternative ports and hosts. Otherwise, a warning is displayed and client reroute is not enabled.
  4. Optional: Enable client reroute with the persistence option.
    1. Complete the field for Client reroute server list JNDI name.
      The field specifies the JNDI name that is used to bind the Db2 client reroute server list into the JNDI namespace. The application server uses this name to look up the alternative server list after an application server restart.
      Avoid trouble:
      • This option is not supported for Type 2 data sources. If you use a Db2 data source that is configured as a Type 2 JDBC driver, the JDBC driver uses a catalog to persist the client reroute information. If this property is configured with a Type 2 driver, the application server issues a warning.
      • Use different JNDI names among different data sources. Otherwise, when you delete a data source, and the JNDI entry is removed from the namespace, the other data sources that share the JNDI entry are affected.
  5. Configure the retry count and interval for the client reroute function.
    Complete these two fields:
    Retry interval for client reroute
    Specifies the amount of time, in seconds, between retries for automatic client reroute.
    Maximum retries for client reroute
    Specifies the maximum number of connection retries that are attempted by the automatic client reroute function if the primary connection to the server fails. The property is only used when Retry interval for client reroute is set.
  6. Click OK and save the changes.
  7. Restart the application server.

What to do next

If you later want to remove the client reroute information that is bound in JNDI, you can do so by deleting the data source. You can also use the unbind feature with the test connection service to delete the JNDI binding for the client reroute function from the application server's JNDI name space without deleting the data source.
To delete the JNDI binding for client reroute:
  1. Select Unbind client reroute list from JNDI.
  2. Click OK.
  3. Save the configuration.
  4. Click Test connection for the data source.
  5. Clear Unbind client reroute list from JNDI.
  6. Click OK.
  7. Save the configuration.