DB2 Version 10.1 for Linux, UNIX, and Windows

Configuration of DB2 for Linux, UNIX, and Windows automatic client reroute support for non-Java clients

For connections to DB2® for Linux, UNIX, and Windows databases, the process for configuration of automatic client reroute support on non-Java clients is the same for a non-DB2 pureScale® environment and a DB2 pureScale environment.

Automatic client reroute capability is enabled at a non-Java client by default. You must connect to the primary server in a non-DB2 pureScale environment or to a DB2 pureScale instance in a DB2 pureScale environment.

At the first successful connection to the server, the client obtains a list, which the client stores in memory, from the server of all the available alternate servers. If the first connection fails, the client looks for a list of alternate servers that are defined in the db2dsdriver.cfg file, in the <acr> section, under the <alternateserverlist> tag.

If the db2dsdriver.cfg file has no alternate servers that are defined in the <acr> section , upon the first successful connection to the server, the client creates a local cache file, srvrlst.xml. The client updates the file with the server's list of available alternate servers. This file is refreshed whenever a new connection is made and the server's list differs from the contents of the client srvrlst.xml file.

When a client uses the srvrlst.xml file to locate an alternate server, it writes a record to the db2diag log files. You can monitor this log to determine how frequently initial sever connections are failing.

The table 1 describes the basic settings to establish a connection for non-Java applications.

Table 1. Basic settings to establish a connection to a DB2 for Linux, UNIX, and Windows database in non-Java applications
Client setting	Value for a non-DB2 pureScale environment	Value for a DB2 pureScale environment
Connection address:
Database host¹	The IP address of the primary server.	The IP address of a member of a DB2 pureScale instance.²
Database port¹	The SQL port number of the primary server.	The SQL port number of a member of a DB2 pureScale instance.²
Database name¹	The database name.	The database name.
Note: Depending on the client that you use, connection information is defined in one of several possible sources: If you are using one of the data server drivers, a CLI, or an open source application that uses IBM® Data Server Client or IBM Data Server Runtime Client: If host, port, and database information is provided in the connection string in an application, the DB2 database system uses that information. If host, port, and database information is not provided in the connection string in an application, the driver uses a db2cli.ini file, and this information is provided in the db2cli.ini file. If host, port, and database information is not provided in the connection string in the application or the db2cli.ini file, the DB2 database system uses information in the db2dsdriver configuration file. If you are using a .NET application with the IBM Data Server Client or the IBM Data Server Runtime Client, connection information can be defined in the database catalog, connection string, db2dsdriver configuration file, or .NET object properties. If you are using an embedded SQL application with the IBM Data Server Client or the IBM Data Server Runtime Client, connection information can be defined in the database catalog, connection string, or db2dsdriver configuration file. Alternatively, you can use a distributor, such as WebSphere Application Server Network Deployment, or multihomed DNS to establish the initial connection to the database. For a distributor, you specify the IP address and port number of the distributor. The distributor analyzes the current workload distribution, and uses that information to forward the connection request to one of the members of the DB2 pureScale instance. For multihomed DNS, you specify an IP address and port number that can resolve to the IP address and port number of any member of the DB2 pureScale instance. Multihomed DNS processing selects a member based on criteria, such as simple round-robin selection or member workload distribution.

You can set configuration keywords or registry variables in the db2dsdriver.cfg file to refine automatic client reroute behavior. You can use the configuration keywords in the table 2 to control automatic client reroute. The keywords are described for the case in which client affinities are not enabled.

In case of changes to the db2dsdriver.cfg file, your CLI application can start the SQLReloadConfig function to validate the entries for all alternate servers within the <acr> section.

Table 2. Settings to control automatic client reroute behavior
Element in the <acr> section of the db2dsdriver configuration file	Value
enableAcr parameter	Specifies whether automatic client reroute is in effect. The default is true.
enableSeamlessAcr parameter	Specifies whether seamless failover can occur. If enableAcr is set to true, the default for enableSeamlessAcr is true. enableSeamlessACR applies only to the members within a group or cluster.
enableAlternateGroupSeamlessACR parameter	Specifies seamless or non-seamless failover behavior across groups. The default is false. You must define this parameter in the <alternategroup> element in the <acr> section. To set this parameter to true, you must also set enableSeamlessACR to true. Setting this parameter to true, does not affect the setting of enableSeamlessACR. If a successful connection is established to a server in the `alternategroup` section, the rules for seamless or non-seamless behavior still apply.
acrRetryInterval parameter	The number of seconds to wait between consecutive connection retries. The registry variable DB2_CONNRETRIES_INTERVAL overrides this value. The valid range is 0 to MAX_INT. The default is no wait (0), if DB2_CONNRETRIES_INTERVAL is not set.
maxAcrRetries parameter	Specifies the maximum number of connection attempts for automatic client reroute. The valid range is 0 to MAX_INT. The value of the DB2_MAX_CLIENT_CONNRETRIES registry variable overrides this value. If you do not set the DB2_MAX_CLIENT_CONNRETRIES registry variable or maxAcrRetries parameter, by default the connection is tried again for 10 minutes. However, if alternate groups are defined, by default, a connection is attempted for 2 minutes. Setting this value to 0 disables ACR.
enableAlternateServerListFirstConnect parameter	Specifies whether there is an alternate server list that is used only if a failure occurs on the first connection to the data server. The default is false. When the value of enableAlternateServerListFirstConnect is true, automatic client reroute with seamless failover is implicitly enabled, regardless of the other settings that are specified for automatic client reroute in the db2dsdriver configuration file. To use this feature, you also require an <alternateserverlist> element in the db2dsdriver configuration file.
alternateserverlist parameter	Specifies a set of server names and port numbers that identify alternate servers to which a connection is attempted if a failure occurs on the first connection to the database. The alternate server list is not used after the first connection. In a DB2 pureScale environment, the entries in the list can be members of a DB2 pureScale instance. In a non-DB2 pureScale environment, there is an entry for the primary server and an entry for the high availability disaster recovery (HADR) standby server. The alternate server list is not used after the first connection.

The registry variables in table 3 controls retry behavior of automatic client reroute.

Table 3. Registry variables to control automatic client reroute retry behavior
Registry variable	Value
DB2_MAX_CLIENT_CONNRETRIES	The maximum number of connection retries for automatic client reroute. The default is 30 if DB2_CONNRETRIES_INTERVAL is set.
DB2_CONNRETRIES_INTERVAL	The number of seconds between consecutive connection retries. The default is 10 if DB2_MAX_CLIENT_CONNRETRIES is set.

If neither registry variable is set, and maxAcrRetries and acrRetryInterval are also not set, automatic client reroute processing tries the connection to a database again for up to 10 minutes, with no wait between retries.

For CLI, OLE DB, ADO.NET, and embedded SQL applications, there are two connection timeout keywords, which you can set in the IBM data server driver configuration file (db2dsdriver.cfg):

tcipipConnectionTimeout: The tcipipConnectionTimeout keyword specifies the number of seconds before an attempt to open a socket fails. Do not use this keyword with automatic client reroute.
ConnectionTimeout: The ConnectionTimeout keyword specifies the number of seconds that a client application waits for a connection to a DB2 for z/OS® data sharing group to be established.

The ConnectionTimeout keyword setting takes precedence over the tcpipConnectTimeout and MemberConnectTimeout keyword settings. End of change

For embedded SQL, CLI, OLE DB, and ADO.NET applications, you can set a connection timeout value. That value specifies the number of seconds that the client application waits for a connection to a database to be established. You must set the connection timeout value to a value that is equal to or greater than the maximum time that it takes to connect to the server. Otherwise, the connection might time out and be rerouted to the alternate server by client reroute. For example, if on a normal day it takes about 10 seconds to connect to the server, and on a busy day it takes about 20 seconds, you should set the connection timeout value t to at least 20 seconds.