Alternate groups for connections to Db2 for z/OS servers from non-Java clients

To improve high availability for non-Java clients in Version 9.7 Fix Pack 5 or later fix pack releases, use alternate groups as an additional failover mechanism for automatic client rerouting when connectivity to the current group cannot be re-established.

By default, non-Java clients have the automatic client reroute (ACR) enabled. This capability provides automatic failover to alternate servers within the current group when connectivity to a server cannot be re-established.

In addition to this ACR capability, you can define alternate groups as failover targets when connectivity to the current group cannot be established. To define alternate groups for non-Java clients:
  • Define one <database> element inside the <alternategroup> element in the <acr> section of the db2dsdriver.cfg file. Do not specify <parameter> elements inside the <database> element, parameter settings are inherited from the primary group.
  • If you want to suppress error messages from failover connections to the alternate group, set the enableAlternateGroupSeamlessACR parameter to true in <alternategroup> element.

For Db2 for z/OS, you can define only one database in the alternate group. If you define more than one Db2 for z/OS, the connection is terminated and the client returns an error.

When a non-Java client is connected to an alternate group, all the connection settings and the parameter settings for the <database> element in the primary group are inherited by the connection to the database in the alternate group.

After a non-Java client is connected to a database in the alternate group, no failback to the primary group is provided. To connect to the primary group again, the application or client must be restarted.

Alternate groups are only supported for ACR and workload balancing. If client affinities is configured, alternate group definitions are ignored.

Examples

Here is an example of alternate group definitions in the db2dsdriver.cfg file:

<dsncollection>
  <dsn alias="mydsn2" name="mydb2" host="myserver2.ibm.com" port="5912">
  ...
</dsncollection>

<databases>
  <database name="mydb2" host="myserver2.ibm.com" port="5912">
   <parameter name="IsolationLevel" value="4"/>
...
   <wlb>
     <parameter name="enableWLB" value="true"/>
   </wlb>
   <acr>
... 
    <alternategroup>
       <parameter name="enableAlternateGroupSeamlessACR" value="true"/>
       <database name="mydb3" host="myserver3.ibm.com" port="5912">
       </database>
     </alternategroup>
   </acr>
  </database> 

  <database name="mydb3" host="myserver3.ibm.com" port="5912">
   <parameter name="IsolationLevel" value="2"/>
...    
   <acr>
     <parameter name="enableACR" value="true"/>
...
    <alternategroup>
       <parameter name="enableAlternateGroupSeamlessACR" value="true"/>
       <database name="mydb4" host="myserver4.ibm.com" port="5912">
       </database>
     </alternategroup>
    
   </acr>
...
  </database> 
</databases>
The following example scenarios demonstrate how automatic client rerouting works for alternate groups. The details about ACR failover to the current group are not covered in these scenarios to focus on the alternate groups failover details. These scenarios use the db2dsdriver.cfg sample that is described in the previous paragraph.
First connection to the primary
In this example, after a non-Java™ client fails to connect to the primary group on its first attempt, the connection to an alternate group is attempted:
  1. The client fails to connect to the mydb2 database.
  2. The client tries to connect to the alternate group listed in the <alternategroup> section of the db2dsdriver.cfg file in the order specified in this file.
    1. The client successfully connects to the mydb3 database.
Subsequent connection after the loss of existing connection to the primary server
In this example, after a non-Java client loses its connection to the mydb3 database, the following connection attempts are made:
  1. The client fails to connect to all the members returned in the server list.
  2. The client fails to connect to the mydb3 database once again.
  3. The client tries to connect to an alternate group listed in the <alternategroup> section of the db2dsdriver.cfg file.
    1. The client successfully connects to the mydb4 database.

When connecting to Db2 for z/OS server, only one <database> element is allowed under the <alternategroup> section.

Existing connection to an alternate group
A non-Java client fails to connect to the mydb2 database, automatic client reroute failover to alternate servers in the current group also fails, and then it successfully connects to the mydb3 database in the alternate group.

If communication error is encountered, you must restart the client or the application must try connecting to the primary group again.