Configuration of Db2 automatic client reroute support for applications other than Java
For connections to Db2 databases, the process for configuration of automatic client reroute support for applications other than Java™ is the same for Db2 pureScale® environment and other environments.
Automatic client reroute capability is enabled by default. You must connect to a Db2 pureScale instance in a Db2 pureScale environment or to the primary server in other environments.
At the first successful connection to the server, the client obtains a list from the server of all the available alternate servers, which the client stores in memory. If the first connection fails, the client checks for a list of alternate servers that is 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 in the db2diag.log file. You can monitor this log to determine how frequently initial server connections fail.
Table 1 describes the basic settings to establish a connection for applications other than Java.
|Client setting||Value for a Db2 pureScale environment||Value for other environments|
|Database host (host)1||The IP address of a member of a Db2 pureScale instance2||The IP address of the primary server|
|Database port (port)1||The SQL port number of a member of a Db2 pureScale instance2||The SQL port number of the primary server|
|Database name (name)1||The database name||The database name|
You can set configuration keywords or registry variables in the IBM data server driver configuration file (db2dsdriver.cfg) to modify the automatic client reroute behavior. The configuration keywords that you can use to control automatic client reroute are in Table 2. The keywords are described for the case in which client affinities are not enabled.
|Element in the <acr> section of the db2dsdriver configuration file||Value|
|acrRetryInterval keyword||Specifies the number of seconds to wait
between consecutive connection retries. The value of the DB2_CONNRETRIES_INTERVAL registry
variable overrides this value. The range of the acrRetryInterval keyword
is 0 - the maximum integer value (
|alternateserverlist keyword||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 other environments, the list contains an entry for the primary server and an entry for the high availability disaster recovery (HADR) standby server.|
whether a connection to a new member can seamlessly fail over with the automatic client reroute
feature enabled, even if the failed statement is not the first SQL statement in a transaction. The
detectReadonlyTxn keyword is valid when you are connecting to a Db2 Cancun Release
10.5.0.4 or later server. The default value of the
detectReadonlyTxn keyword is true for connection to supported
The true value forces the connected server to return the current values of special registers whenever they are modified.
Restriction: You cannot set the detectReadonlyTxn keyword to true in a transaction with the repeatable read (RR) or read stability (RS) isolation level.
|enableAcr keyword||Specifies whether automatic client reroute is in effect. The default is true.|
|enableAlternateGroupSeamlessACR keyword||Specifies seamless or non-seamless failover behavior across groups. The default is false. You must define this keyword in the <alternategroup> element in the <acr> section. To set this keyword to true, you must also set the enableSeamlessACR keyword to true. Setting the enableAlternateGroupSeamlessACR keyword to true does not affect the setting of the enableSeamlessACR keyword. If a successful connection is established to a server in the alternategroup section, the rules for seamless or non-seamless behavior still apply.|
|enableAlternateServerListFirstConnect keyword||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 the enableAlternateServerListFirstConnect keyword is true, automatic client reroute with seamless failover is implicitly enabled, regardless of the other settings that you specify for automatic client reroute in the db2dsdriver.cfg file. To use this feature, you also require a <alternateserverlist> element in the db2dsdriver.cfg file.|
|enableSeamlessAcr keyword||Specifies whether seamless failover can occur. If the enableAcr keyword is set to true, the default for the enableSeamlessAcr keyword is true. The enableSeamlessACR keyword applies only to the members within a group or cluster.|
the maximum number of connection attempts for automatic client reroute. The valid range is
0 - the maximum integer value (
In case of changes to the db2dsdriver.cfg file, your CLI application can issue the SQLReloadConfig function to validate the entries for all alternate servers within the <acr> section.
The registry variables in Table 3 control the retry behavior of automatic client reroute.
|DB2_CONNRETRIES_INTERVAL||The number of seconds between consecutive connection retries. The default is 10 if you set the DB2_MAX_CLIENT_CONNRETRIES registry variable.|
|DB2_MAX_CLIENT_CONNRETRIES||The maximum number of connection retries for automatic client reroute. The default is 30 if you set the DB2_CONNRETRIES_INTERVAL registry variable.|
If you do not set either registry variable and also do not set the maxAcrRetries and acrRetryInterval keywords, automatic client reroute processing tries the connection to a database again for up to 10 minutes, with no wait between retries.
- 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.
- 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.
For embedded SQL, CLI, OLE DB, and ADO.NET applications, you can set a connection timeout value by setting the ConnectionTimeout keyword. 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 approximately 10 seconds to connect to the server and on a busy day it takes approximately 20 seconds, you should set the connection timeout value to at least 20 seconds.