DB2 Version 9.7 for Linux, UNIX, and Windows

db2dsdriver configuration file

The db2dsdriver.cfg configuration file contains database directory information and client configuration parameters in a human-readable format.

The db2dsdriver.cfg configuration file is an XML file that is based on the db2dsdriver.xsd schema definition file. The db2dsdriver.cfg configuration file contains various keywords and values that can be used to enable various features to a supported database through ODBC, CLI, .NET, OLE DB, PHP, Ruby, or embedded SQL applications. The keywords can be associated globally for all database connections, or they can be associated with a specific database source name (DSN) or database connection. You can also use this configuration file to enable high availability connection to supported databases.

The db2dsdriver.cfg file can be used with embedded SQL applications, ODBC, CLI, .NET, OLE DB, PHP, or Ruby drivers. You do not have to create and populate the db2dsdriver.cfg configuration file for these drivers. The applications can function without this configuration file. However, instead of specifying information about the database name, host, port, and configuration parameters in your applications, you can use the configuration file to define aliases.

Note: The db2dsdriver.cfg configuration file supports a consistent set of XML tags that are in lowercase and do not include underscores (_). XML tag attributes, which are where IBM® Data Server Driver configuration keywords are specified, can contain uppercase, lowercase and underscores (_) characters.

db2dsdriver configuration file structure

The scope of configuration keywords and their associated values are defined by the position of configuration keywords in the db2dsdriver.cfg file. Depending on the position of the configuration keyword, the keyword can have a global effect (affecting all connections) or it might affect only the specific database connection made to that database or alias. Some keywords can be specified only in a specific section. The db2dsdriver.cfg configuration file contains following sections:

<dsncollection>: The data source name section is contained within the <dsncollection> and </dsncollection> tags. Parameters in this section apply only to the given data source name.
<databases>: The database information section is contained within the <databases> and </databases> tags. Parameters in this section apply only to the given database connection.
Two subsections can be defined under the database information section to enable high availability features:
- <wlb>: The workload balancing subsection is contained within the <wlb> and </wlb>tags. Workload-balance related parameters are placed in this section, and they apply to a specific database connection.
- <acr>: The automatic client reroute subsection is contained within the <acr> and </acr> tags. Automatic client reroute related parameters are placed in this section, and they apply to a specific database connection.
<parameters>: The global attributes section is contained within the <parameters> and </parameters> tags. Parameters in this section apply to all databases and aliases.
<ldapserver>: The LDAP section is contained within the <ldapserver> and </ldapserver> tags. Parameters in the LDAP section can be used to specify LDAP server information. Only one LDAP section is allowed in the db2dsdriver.cfg file. The LDAP section settings are not recognized by the .NET and embedded applications.

If you specify multiple entries of the same parameter, with different values, in the same section of a db2dsdriver.cfg file, you cannot determine which parameter value takes effect.

Example db2dsdriver.cfg file

Here is a sample db2dsdriver.cfg configuration file with <dsncollection>, <database>, and <parameters> sections.

<configuration>
	<dsncollection>
		<dsn alias="alias1" name="name1" host="server1.net1.com" port="50001"/>
		<!-- Long aliases are supported -->
		<dsn alias="longaliasname2" name="name2" host="server2.net1.com" port="55551">
			<parameter name="Authentication" value="Client"/>
		</dsn>
	</dsncollection>
	<databases>
		<database name="name1" host="server1.net1.com" port="50001">
			<parameter name="CurrentSchema" value="OWNER1"/>
			<wlb>
				<parameter name="enableWLB" value="true"/>
				<parameter name="maxTransports" value="50"/>
			</wlb>
			<acr>
				<parameter name="enableACR" value="true"/>
			</acr>
		</database>
		<!-- Local IPC connection -->
		<database name="name3" host="localhost" port="0">
			<parameter name="IPCInstance" value="DB2"/>
			<parameter name="CommProtocol" value="IPC"/>
		</database>
	</databases>
	<parameters>
		<parameter name="GlobalParam" value="Value"/>
	</parameters>
</configuration>

db2dsdriver configuration file restrictions

The following restrictions apply to the db2dsdriver.cfg configuration file:

The configuration file cannot contain multiple identical entries for a database with the following properties: database name, server name, and port number. In addition, the configuration file cannot contain multiple identical database alias entries.
The <dsncollection> entries (alias, name, host, and port) and the <database> entries (name, host, port) must contain a value.
If multiple parameters are defined on a single line, they are ignored.
Only one LDAP section (<ldapserver>) is allowed in the db2dsdriver.cfg file.
The LDAP section (<ldapserver>) settings are not recognized by the .NET and embedded applications.

db2dsdriver configuration file location

In Version 9.7 Fix Pack 3 and later fix packs, the db2dsdriver.cfg configuration file is not provided with DB2® software. Instead, the db2dsdriver.cfg.sample sample configuration file is provided to help you get started. Use the contents of the db2dsdriver.cfg.sample file to create a db2dsdriver.cfg file in the same location as the sample configuration file. The location of the sample configuration file depends on your driver type and platform:

For IBM Data Server Client, IBM Data Server Runtime Client, or IBM Data Server Driver Package, the configuration file is created in one of the listed paths:
- On AIX®, HP-UX, Linux, or Solaris operating systems: instance_path/cfg
- On Windows XP Professional and Windows Server 2003: C:\Documents and Settings\All Users\Application Data\IBM\DB2\driver_copy_name\cfg
- On Windows Vista, Windows 7, and Windows Server 2008: C:\ProgramData\IBM\DB2\driver_copy_name\cfg
For example, if you use IBM Data Server Driver Package for Windows XP Professional or Windows Server 2003, and the data server driver copy name is IBMDBCL1, then the db2dsdriver.cfg.sample file is created in the C:\Documents and Settings\All Users\Application Data\IBM\DB2\IBMDBCL1\cfg directory.
For IBM Data Server Driver for ODBC and CLI, the configuration file is created in one of the listed paths:
- On AIX, HP-UX, Linux, or Solaris operating systems: instance_path/cfg
- On Windows XP and Windows Server 2003: C:\Documents and Settings\All Users\Application Data\IBM\DB2\installation_path\cfg.
- On Windows Vista and Windows Server 2008: C:\ProgramData\IBM\DB2\installation_path\cfg.
Note: On Windows operating systems, the sample configuration file is created when you run the db2cli install -setup command with the administrator authority:
For example, if you use IBM Data Server Driver for ODBC and CLI for Windows Vista, and the driver is extracted to the C:\IBMDB2\CLIDRIVER directory, then the db2dsdriver.cfg.sample file is created in the C:\ProgramData\IBM\DB2\C_IBMDB2_CLIDRIVER\cfg directory.

If you use a copy of the db2dsdriver.cfg file from Version 9.7 Fix Pack 2 or earlier on Windows, the file is in a different location. You must back up existing db2dsdriver.cfg file to a different path and copy it back to the new default configuration file path.

You can use the DB2DSDRIVER_CFG_PATH registry variable to specify a different location for the db2dsdriver.cfg file.

The db2dsdriver.cfg configuration file can be copied and edited manually. After editing the file, you must restart your ODBC, CLI, .NET, OLE DB, PHP, Ruby, or embedded SQL applications for the changes to take effect.

If you have an IBM Data Server Runtime Client or IBM Data Server Client, you can copy the existing database directory information into the db2dsdriver.cfg configuration file by using the db2dsdcfgfill command. When you run this command, the configuration file is populated based on the contents of the local database directory, node directory, and Database Connection Services (DCS) directory of a specific database manager instance.

If you have an IBM Data Server Driver for ODBC and CLI client, you can create the db2dsdriver.cfg.sample and db2cli.ini.sample sample configuration files by using the db2oreg1.exe utility or db2cli install -setup command.

IBM Data Server Client and IBM Data Server Runtime Client can catalog remote databases locally. In Version 9.7 Fix Pack 3 and later fix packs, you can define client parameters for the databases that are cataloged. IBM Data Server Client and IBM Data Server Runtime Client derive database, host, and port information from the database and node catalog directories and use that information to locate the corresponding entry in the db2dsdriver.cfg configuration file. Even if the DCS (database connection services) directory is cataloged using a different target database, the database name specified in the database directory is used to locate the corresponding entry in the db2dsdriver.cfg file.

Database details order of precedence

Depending on the DB2 product and application you use, connection information is obtained in the listed order of precedence.

◦In a scenario that involves a CLI or open source application with anIBM data server client, connection information is obtained in the following order of precedence:

The connection string.
Database, Node, and DCS directories.
The db2cli.ini file.
The db2dsdriver.cfg file.

◦In a scenario that involves a CLI or open source application with an IBM data server driver, connection information is obtained in following order of precedence:

The connection string.
The db2cli.ini file.
The db2dsdriver.cfg file.

◦In a scenario that involves a .NET application with an IBM data server client, connection information is obtained in following order of precedence:

The connection string or information provided through .NET object properties (DB2ConnectionStringBuilder properties).
Database, Node, and DCS directories.
The db2dsdriver.cfg file.

◦In a scenario that involves a .NET application with an IBM data server driver, connection information is obtained in following order of precedence:

The connection string or information provided through .NET object properties (DB2ConnectionStringBuilder properties).
The db2dsdriver.cfg file.

◦In a scenario that involves an embedded SQL application with an IBM data server client, connection information is obtained in following order of precedence:

The connection string.
Database, Node, and DCS directories.
The db2dsdriver.cfg file.

◦In a scenario that involves an embedded SQL application with an IBM data server driver, connection information is obtained in following order of precedence:

The connection string.
The db2dsdriver.cfg file.