DB2 Version 10.1 for Linux, UNIX, and Windows

Configuring client affinities in non-Java clients for connection to DB2® for Linux, UNIX, and Windows

To enable support for client affinities in CLI and .NET applications, you set values in the db2dsdriver.cfg configuration file to indicate that you want to use client affinities, and to specify the primary and alternate servers.

The following table describes the settings in the db2dsdriver.cfg file for enabling client affinities for CLI and .NET applications.

Table 1. Settings to enable client affinities for CLI and .NET applications
Element in the acr section of the db2dsdriver configuration file	Values
enableAcr parameter	true
maxAcrRetries parameter	The maximum number of connection attempts to each server in the list of alternate servers for automatic client reroute (ACR). The valid range is 0 - (the value of the MAX_INT).
acrRetryInterval parameter	The number of seconds to wait between retries.
affinityFailbackInterval parameter	The number of seconds to wait after the first transaction boundary to fail back to the primary server. Set this value if you want to fail back to the primary server. The default is 0, which means that no attempt is made to fail back to the primary server.
alternateserverlist	<server> elements that identify the host name and port number for each server that is used for automatic client reroute through client affinities. One of the elements must identify the primary server. The presence of these elements does not activate automatic client reroute.
affinitylist	<list> elements with serverorder attributes. The serverorder attribute value specifies a list of servers, in the order that they should be tried during automatic client reroute with client affinities. The servers in <list> elements must also be defined in <server> elements in the <alternateserverlist>. You can specify multiple <list> elements, each of which has different server orders. The presence of the <affinitylist> element does not activate automatic client reroute.
client_affinity	A <clientaffinitydefined> element or a <clientaffinityroundrobin> element that defines the order in which to try server connections for each client. When you include a <clientaffinitydefined> element, you define the server order by defining <client> elements, each of which specifies a <list> element that defines the server order. When you include a <clientaffinityroundrobin> element, you also specify <client> elements, but those <client> elements do not specify a <list> element. Instead, the order of the <client> elements, defines the server order. All clients that connect to a database must be specified within a <clientaffinitydefined> or a <clientaffinityroundrobin> element. In case of multiple network interface cards on a given client machine, client host name will be self discovered and matched with the configuration file entry, by CLI driver, to compute the affinity list. CLI driver will get all network interfaces and will try to match it with the host names available in the db2dsdriver configuration file. When a hostname without domain name is specified in db2dsdriver.cfg, CLI will try to resolve it using the default domain and will try to match with the discovered hostname. If the IP address is defined under client affinity section of the cfg file, the respective IP address will be discovered and matched (for hostname ) with configuration file entry, by CLI driver, to compute the affinity list.
clientaffinitydefined	<client> elements that define the server order for automatic client reroute for each client. Each <client> element contains a listname attribute that associates a client with a <list> element from the <affinitylist> element.
clientaffinityroundrobin	<client> elements whose order in the <clientaffinityroundrobin> element defines the first server that is chosen for automatic client reroute. Each <client> element has an index. The first <client> element in the <clientaffinityroundrobin> element has index 0, the second <client> element has index 1, and so on. Suppose that the number of servers in the <alternateserverlist> element is `n` and the index in the <clientaffinityroundrobin> element of a <client> element is `i`. The first server to be tried is the server whose index in the <alternateserverlist> element is `i` mod `n`. The next server to be tried is the server whose index in the <alternateserverlist> element is (`i` +1) mod `n`), and so on.

The following restrictions apply to configuration of client affinities for CLI or .NET clients:

If the total number of qualifying alternate servers for a given client is greater than 128, error SQL1042N occurs.
Workload balancing cannot be enabled when client affinity is enabled. That is, if enableWLB is set to true, and the client_affinity element is specified, error SQL5162N occurs.
If the required attributes are not specified in the <alternateserverlist>, <affinitylist> or <client_affinity> elements, error SQL5163N occurs.
If client affinity is enabled, and the <alternateserverlist> element is empty, error SQL5164N occurs.
If client affinity is enabled, and the host name for a client that is attempting to connect to a server is not in one of the <client_affinity> subgroups (<clientaffinitydefined> or <clientaffinityroundrobin>), or is in more than one of the subgroups, error SQL5164N occurs.
For each client machine, there should be only one entry, either in <clientaffinitydefined> or <clientaffinityroundrobin> section. If there are entries in db2dsdriver.cfg where the same client machine has been specified by different host names, the error SQL5162N occurs.