db2cli.ini initialization file

The db2cli.ini file contains various keywords and values that you can use to configure the behavior of the CLI/ODBC driver and CLI/ODBC applications. The keywords can be associated with a specific database connection or all database connections by CLI and ODBC applications.

To help you get started, the db2cli.ini.sample sample configuration file is included with the IBM® data server products.

You can create a db2cli.ini file that is based on the db2cli.ini.sample file and place the db2cli.ini file in the same location as the db2cli.ini.sample file. The location of the sample configuration file depends on your IBM data server product and the operating system.

On Windows operating systems, there might also be a user-level db2cli.ini initialization file. Depending on the version of Windows operating system, the user-level db2cli.ini initialization file is stored in the \Documents and Settings\UserName or the \Users\UserName directory, where UserName represents the name of the logged in user. If there is a user-level db2cli.ini initialization file for the logged in user, the values in the user-level db2cli.ini initialization file take precedence over any other db2cli.ini initialization file. That is, if the same CLI configuration parameter is present in the user-level db2cli.ini initialization file as in any other db2cli.ini initialization file, it is the value in the user-leveldb2cli.ini initialization file that takes effect

For IBM Data Server Client, IBM Data Server Runtime Client, or IBM Data Server Driver Package, the sample configuration file is created in one of the following paths:
  • On AIX® or Linux® operating systems: the installation_path/cfg directory
  • On Windows operating systems: the C:\ProgramData\IBM\Db2\driver_copy_name\cfg directory
The installation_path value represents the directory into which you installed the IBM data server product. For example, if you install the IBM Data Server Driver Package product on the Windows 7 operating system, and the data server driver copy name is IBMDBCL1, the db2cli.ini.sample file is created in the C:\ProgramData\IBM\Db2\IBMDBCL1\cfg directory.
For the IBM Data Server Driver for ODBC and CLI product installation, the sample configuration file is created in one of the following paths:
  • On AIX or Linux operating systems: the installation_path/cfg directory
  • On Windows operating systems: the C:\ProgramData\IBM\Db2\installation_path\cfg directory when you run the db2cli install -setup command with administrator authority
The installation_path value represents the directory into which you extracted the IBM Data Server Driver for ODBC and CLI product. For example, if you install the IBM Data Server Driver for ODBC and CLI product on the Windows 7 operating system into the C:\IBMDB2\CLIDRIVER\ directory, the db2cli.ini.sample file is created in the C:\ProgramData\IBM\DB2\C_IBMDB2_CLIDRIVER\cfg directory.

You can use the DB2CLIINIPATH environment variable to specify a different location for the db2cli.ini file.

You can use the CLI/ODBC configuration keywords to perform the following tasks:
  • Configure general settings such as the data source name, user name, and password.
  • Set options that can affect performance.
  • Set query parameters such as wildcard characters.
  • Specify patches or workarounds for various ODBC applications.
  • Specify settings that are associated with the connection, such as code pages and IBM GRAPHIC data types.
  • Override default connection options that are specified by an application. For example, if an application requests Unicode support from the CLI driver by setting the SQL_ATTR_ANSI_APP connection attribute, setting the DisableUnicode keyword to 1 in the db2cli.ini file forces the CLI driver not to provide the application with Unicode support.
    Important: If the values of the CLI/ODBC configuration keywords that you set in the db2cli.ini file conflict with the values of keywords in the SQLDriverConnect() connection string, the values of the SQLDriverConnect() keywords take precedence.

You can set most CLI/ODBC keywords in the db2cli.ini initialization file. However, you must set some keywords in the connection string for the SQLDriverConnect() function call.

The scope of the CLI/ODBC keywords is determined by the placement of the keywords within the db2cli.ini initialization file. If you specify the CLI keywords in a specific database section (data source section) within the db2cli.ini initialization file, the keywords are applicable only when your CLI/ODBC application is connected to that particular database. If the CLI keywords are listed in the [COMMON] section within the db2cli.ini initialization file, the keywords affect all CLI application connections to databases.

You can specify the following CLI keywords only in the [COMMON] section:
  • CheckForFork
  • DiagPath
  • DisableMultiThread
  • JDBCTrace
  • JDBCTraceFlush
  • JDBCTracePathName
  • QueryTimeoutInterval
  • ReadCommonSectionOnNullConnect
  • Trace
  • TraceComm
  • TraceErrImmediate
  • TraceFileName
  • TraceFlush
  • TraceFlushOnError
  • TraceLocks
  • TracePathName
  • TracePIDList
  • TracePIDTID
  • TraceRefreshInterval
  • TraceStmtOnly
  • TraceTime
  • TraceTimeStamp

The [COMMON] section of the db2cli.ini file begins with the heading [COMMON].

Before you set a common keyword for a client, it is important to evaluate the effect of the keyword on all CLI/ODBC connections from that client. For example, the TRACE keyword generates information about all CLI/ODBC applications that connect to Db2® database servers on that client.

The database-specific section begins with the data source name (DSN) between square brackets: 
[data_source_name]
The name that is enclosed between square brackets is called a section header.
You set a keyword to a value by using the following format: 
KeywordName=keywordValue
The following other rules apply:
  • All the keywords and their associated values for a particular database must be located under the database section header.
  • If the database-specific section does not contain a DBAlias keyword, the data source name is used as the database alias when the connection is established.
  • The keywords are not case-sensitive; however, their values can be.
  • If a database is not found in the db2cli.ini file, the default values for the keywords apply.
  • You introduce comments by putting a semicolon in the first position of a new line.
  • Blank lines are allowed.
  • If duplicate entries for a keyword exist, the first entry is used, and no warning is given.

The UPDATE CLI CONFIGURATION command can be used to update the contents of a specified section in the db2cli.ini initialization file. For example:

db2 UPDATE CLI CFG FOR SECTION dbname USING APPTOKENGEN ON

The following sample db2cli.ini file contains two database alias sections: 
; This is a comment line.
[MYDB22]
AutoCommit=0
TableType="'TABLE','SYSTEM TABLE'"
APPTOKENGEN=ON

; This is another comment line.
[MYDB2MVS]
CurrentSQLID=SAAID
TableType="'TABLE'"
SchemaList="'USER1',CURRENT SQLID,'USER2'"

Although you can edit the db2cli.ini file manually on all operating systems, you can also use the UPDATE CLI CONFIGURATION command if it is available. You must add a blank line after the last entry if you manually edit the db2cli.ini file.