The following connection option descriptions are listed alphabetically by the GUI name that appears on the driver Setup dialog. The connection string attribute name, along with its short name, is listed immediately underneath the GUI name. For example:
In most cases, the GUI name and the attribute name are the same; however, some exceptions exist. If you need to look up an option by its connection string attribute name, please refer to the alphabetical table of connection string attribute names.
Also, a few connection string attributes, for example, Password, do not have equivalent options that appear on the GUI. They are in the list of descriptions alphabetically by their attribute names.
Table 5-3 lists the connection string attributes supported by the DB2 Wire Protocol driver.
where string is an accounting ID.
A string that is automatically added to all Create Table statements. This option is for users who need to add an In Database clause to Create Table statements.
where string is valid syntax for the In Database clause of a Create Table statement.
The name of the default schema that is used to qualify unqualified database objects in dynamically prepared SQL statements. If the attempt to change the current schema fails, the connection fails and you receive the message
Invalid value for Alternate ID. DB2 permissions must be set to SYSADM. (This option is not valid for DB2 V5R1 for iSeries.)
where string is a valid DB2 schema name.
A list of alternate database servers to which the driver will try to connect if the primary database server is unavailable. Specifying a value for this option enables connection failover for the driver. The value you specify must be in the form of a string that defines the physical location of each alternate server. All of the other required connection information for each alternate server is the same as what is defined for the primary server connection.
(IPAddress=ipvalue:TcpPort=
portvalue:{Database | Location}=
databasevalue[, . . .])
You must specify the IP address, port number, and database name (Linux/UNIX/Windows) or location (z/OS and iSeries) of each alternate server.
Sets the CLIENT APPLNAME register on the server. On DB2 for Linux/UNIX/Windows V9.1 and higher, this option also sets the APPL_NAME column of the SYSIBMADM.APPLICATIONS table.
where string is an application name.
If set to 0 (Disabled), the driver does not work with multi-threaded applications. If using the driver with single-threaded applications, this value avoids additional processing required for ODBC thread-safety standards.
Specifies the method the driver uses to authenticate the user to the server when a connection is established. If the specified authentication method is not supported by the database server, the connection fails and the driver generates an error.
If set to 2 (Encrypt UID and Password), the driver sends an encrypted user ID and password to the server for authentication.
If set to 3 (Client Authentication), the driver uses client authentication when establishing a connection. The database server relies on the client to authenticate the user and does not provide additional authentication.
If set to 4 (Kerberos), the driver uses Kerberos authentication. This method supports both Windows Active Directory Kerberos and MIT Kerberos environments.
The number of rows at a time that the driver sends to the database during bulk operations. This value applies to all methods of bulk loading.
where x is a positive integer that specifies the number of rows.
If set to x, the specified number of rows are sent.
where x is an integer that specifies the number of KB.
If set to 0, all binary data, regardless of size, is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file.
If set to x, any binary data exceeding this specified number of KB is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file.
where x is an integer that specifies the number of KB.
If set to 0, all character data regardless of size, is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file.
If set to x, any character data exceeding this specified number of KB is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file.
where schema_name is the name of a valid DB2 schema. If you do not specify a value for this attribute, the driver uses SYSIBM when connected to z/OS, QSYS2 when connected to iSeries, and SYSCAT when connected to Linux/UNIX/Windows.
The IANA code page to be used by the driver to convert character data stored as bit data in character columns (Char, Varchar, Longvarchar, Clob, Char for Bit Data, Varchar for Bit Data, Longvarchar for Bit Data) defined with CCSID 65535.
where IANA_code_page is a valid IANA code page. Refer to
“IBM to IANA Code Page Values” in
Chapter 1 of the
DataDirect Connect Series for ODBC Reference for a list of the most commonly used IBM code pages and their IANA code page equivalents.
If unspecified or set to 0, the driver returns these columns as binary columns (SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY) and does no conversion of the data.
If an IANA code page is specified, the driver returns these columns as character columns in the character set specified. The driver does no conversion of data supplied in bound parameters.
where client_name is the name of the client workstation.
where client_userid is the current user ID.
For DB2 for z/OS, this value is the user ID. If an attempt to change the current schema fails, the connection fails and you receive the message
Invalid value for Alternate ID.
For DB2 for iSeries, this value is the name of the schema to be used as the default qualifier for unqualified object names. If you want to access a table outside of this schema, you must specify the schema name and the table name. For example:
SELECT * FROM Schema.Tablename
user_ID (DB2 for z/OS) |
schema_name (DB2 for iSeries)
user_ID is a valid user ID. DB2 permissions on the user ID must be set to SYSADM.
schema_name is the default schema to use for unqualified object names.
Determines whether the state of connections that are removed from a pool for reuse by another application is reset to the initial configuration of the connection.
If set to 1 (Enabled), the state of connections removed from the connection pool for reuse by an application is reset to the initial configuration of the connection. Resetting the state can negatively impact performance because additional commands must be sent over the network to the server to reset the state of the connection.
The number of times the driver retries connection attempts to the primary database server, and if specified, alternate servers until a successful connection is established.
This option and the Connection Retry Delay connection option, which specifies the wait interval between attempts, can be used in conjunction with failover.
where x is a positive integer from 1 to 65535.
If set to x, the driver retries connection attempts the specified number of times. If a connection is not established during the retry attempts, the driver returns an error that is generated by the last server to which it tried to connect.
The number of seconds the driver waits between connection retry attempts when Connection Retry Count is set to a positive integer.
where x is a positive integer from 1 to 65535.
If set to x, the driver waits between connection retry attempts the specified number of seconds.
A comma-separated list of DB2 schema names used to resolve unqualified function names and data type references in dynamically prepared SQL statements. This value also is used to resolve unqualified stored procedure names specified in CALL statements.
where schema_name is the name of a valid DB2 schema.
where string is the name of a data source.
where database_name is the name of a valid database.
Refer to Chapter 7 “Locking and Isolation Levels” in the
DataDirect Connect Series for ODBC Reference for details about ODBC isolation levels.
If set to 0 (READ_UNCOMMITTED), other processes can be read from the database. Only modified data is locked and is not released until the transaction ends.
If set to 1 (READ_COMMITTED) other processes can change a row that your application has read if the cursor is not on the row you want to change. This level prevents other processes from changing records that your application has changed until your application commits them or ends the transaction. It also prevents your application from reading a modified record that has not been committed by another process.
If set to 2 (REPEATABLE_READ), other processes are prevented from accessing data that your application has read or modified. All read or modified data is locked until transaction ends.
If set to 3 (SERIALIZABLE), other processes are prevented from changing records that are read or changed by your application (including phantom records) until your program commits them or ends the transaction. This level prevents the application from reading modified records that have not been committed by another process. If your application opens the same query during a single unit of work under this isolation level, the results table will be identical to the previous table; however, it can contain updates made by your application.
If set to 4 (NONE), your application can read modified records even if they have not been committed by another application. This level can only be set in the data source, not from the application. (This level is valid only on DB2 for iSeries, and is the only isolation level that works for collections that have journaling disabled.)
An optional long description of a data source. This description is not used as a runtime connection attribute, but does appear in the ODBC.INI section of the Registry and in the odbc.ini file.
where string is a description of a data source.
The driver only keeps the specified number of prepared statements open. If the driver detects that the number of dynamic sections available in the bound DB2 packages is less than the number of dynamic sections requested in the connection string or data source, it generates the following message:
where x is a positive integer that specifies the number of prepared statements.
If set to 1 (Enabled), the driver uses the database bulk load protocols. If the protocols cannot be used, the driver returns an error.
The method the driver uses to encrypt data sent between the driver and the database server. If the specified encryption method is not supported by the database server, the connection fails and the driver returns an error.
If set to 1 (SSL), data is encrypted using SSL. If the server supports protocol negotiation, the driver and server negotiate the use of TLS1, SSL3, or SSL2 in that order.
If set to 2 (Database Encryption), data is encrypted using the DB2 encryption protocol (supported only on DB2 for Linux/UNIX/Windows and DB2 for z/OS).
This option can only be set to 1 or 2 when Authentication Method is set to 0, 1, or 2.
Determines whether the driver fails the entire failover process or continues with the process if errors occur while trying to reestablish a lost connection.
If set to 0 (Non-Atomic), the driver continues with the failover process and posts any errors on the statement on which they occur.
If set to 1 (Atomic) the driver fails the entire failover process if an error is generated as the result of anything other than executing and repositioning a Select statement. If an error is generated as a result of repositioning a result set to the last row position, the driver continues with the failover process, but generates a warning that the Select statement must be reissued.
If set to 2 (Atomic including Repositioning), the driver fails the entire failover process if any error is generated as the result of restoring the state of the connection or the state of work in progress.
If set to 3 (Disable Integrity Check), the driver does not verify that the rows that were restored during the failover process match the original rows. This value applies only when Failover Mode is set to 2 (Select).
If set to 1 (Extended Connection), the driver provides failover protection for new and lost connections, but not any work in progress.
If set to 2 (Select), the driver provides failover protection for new and lost connections. In addition, it preserves the state of work performed by the last Select statement executed.
This attribute applies only when Failover Mode is set to 1 (Extended Connection) or 2 (Select) and at least one alternate server is specified.
If set to 0 (Disabled), the driver tries to connect to an alternate server only when failover is caused by an unsuccessful connection attempt or a lost connection. This value provides the best performance, but your application typically experiences a short wait while the failover connection is attempted.
If set to 1 (Enabled), the driver tries to connect to the primary and an alternate server at the same time. This can be useful if your application is time-sensitive and cannot absorb the wait for the failover connection to succeed.
If set to 1 (Enabled), EXECUTE privileges are granted on DB2 packages that you are creating. By default, the schema to which privileges are granted is PUBLIC.
where schema_name is the name of a valid DB2 schema.
where client_library is a GSS client library installed on the client.
If set to client_library, the driver uses the specified GSS client library.
A host name for certificate validation when SSL encryption is enabled (Encryption Method=SSL) and validation is enabled (Validate Server Certificate=1). This option provides additional security against man-in-the-middle (MITM) attacks by ensuring that the server the driver is connecting to is the server that was requested.
where the host_name is the host name specified in the certificate. Consult your SSL administrator for the correct value.
If set to a host name, the driver examines the subjectAltName values included in the certificate. If a dnsName value is present in the subjectAltName values, then the driver compares the value specified for Host Name In Certificate with the dnsName value. The connection succeeds if the values match. The connection fails if the Host Name In Certificate value does not match the dnsName value.
If no subjectAltName values exist or a dnsName value is not in the list of subjectAltName values, then the driver compares the value specified for Host Name In Certificate with the commonName part of the Subject name in the certificate. The commonName typically contains the host name of the machine for which the certificate was created. The connection succeeds if the values match. The connection fails if the Host Name In Certificate value does not match the commonName. If multiple commonName parts exist in the Subject name of the certificate, the connection succeeds if the Host Name In Certificate value matches any of the Common Name parts.
If set to #SERVERNAME#, then the driver compares the host server name specified as part of a data source or connection string to the dnsName value or the commonName.

IANAAppCodePage
An Internet Assigned Numbers Authority (IANA) value. You must specify a value for this option if your application is not Unicode‑enabled or if your database character set is not Unicode. Refer to
Chapter 4 “Internationalization, Localization, and Unicode” in the
DataDirect Connect Series for ODBC Reference for details.
If the driver does not find an IANAAppCodePage value, the driver uses the default value of 4 (ISO 8859-1 Latin-1).
where IANA_code_page is one of the valid values listed in
Chapter 1 “Values for the Attribute IANAAppCodePage” in the
DataDirect Connect Series for ODBC Reference. The value must match the database character encoding and the system locale.
host_name is the host name of the machine where catalog tables are stored. The driver must be able to find this name (with the correct address assignment) in the HOSTS file on the workstation or in a DNS server.
IP_address is the IP address of the machine where catalog tables are stored. The IP address can be specified in either IPv4 or IPv6 format, or a combination of the two. See
“Using IP Addresses” for details about these formats.
The password used to access the individual keys in the keystore file when SSL is enabled (Encryption Method=1) and SSL client authentication is enabled on the database server. Keys stored in a keystore can be individually password-protected. To extract the key from the keystore, the driver must have the password of the key.
where key_password is the password of a key in the keystore.
The directory of the keystore file to be used when SSL is enabled (Encryption Method=1) and SSL client authentication is enabled on the database server. The keystore file contains the certificates that the client sends to the server in response to the server’s certificate request.
where keystore_directory is the location of the keystore file.
The password used to access the keystore file when SSL is enabled (Encryption Method=1) and SSL client authentication is enabled on the database server. The keystore file contains the certificates that the client sends to the server in response to the server’s certificate request.
where keystore_password is the password of the keystore file.
where x is a positive integer.
If set to x, inactive connections are closed after the specified number of seconds passes.
Determines whether the driver uses client load balancing in its attempts to connect to the database servers (primary and alternate). You can specify one or multiple alternate servers by setting the Alternate Servers option.
If set to 1 (Enabled), the driver uses client load balancing and attempts to connect to the database servers (primary and alternate servers) in random order.
If set to 0 (Disabled), the driver does not use client load balancing and connects to each server based on their sequential order (primary server first, then, alternate servers in the order they are specified).
On DB2 for iSeries, your system administrator can determine the name of your DB2 location using the
WRKRDBDIRE command. The name of the database that is listed as *LOCAL is the value to use.
where location_name is the name of a valid DB2 location.
The number of seconds the driver waits for a connection to be established before returning control to the application and generating a timeout error. To override the value that is set by this connection option for an individual statement, set a different value in the SQL_ATTR_LOGIN_TIMEOUT statement attribute.
where x is a positive integer that specifies a number of seconds.
If set to -1, the connection request does not time out. The driver silently ignores the SQL_ATTR_LOGIN_TIMEOUT attribute on the SQLSetConnectAttr() function.
If set to 0, the connection request does not time out, but the driver responds to the SQL_ATTR_LOGIN_TIMEOUT attribute on the SQLSetConnectAttr() function.
If set to x, the connection request times out after the specified number of seconds unless the application overrides this setting with the SQL_ATTR_LOGIN_TIMEOUT attribute on the SQLSetConnectAttr() function.
The maximum number of connections allowed within a single connection pool. When the maximum number of connections is reached, no additional connections can be created in the connection pool.
The minimum number of connections that are opened and placed in a connection pool, in addition to the active connection, when the pool is created. The connection pool retains this number of connections, even when some connections exceed their Load Balance Timeout value.
where x is an integer from 1 to 65535.
The name of the DB2 collection or location where the driver creates bind packages and, when required, searches for them.
where collection_name is a valid DB2 collection or location name.
A two-character prefix to be used for package names the driver uses for executing dynamic SQL. The default package name uses the following syntax:
DD is the two-character prefix.
i is one of the following characters:
n
|
R—Repeatable Read : DB2 RS
|
n
|
U—Uncommited Read : DB2 UC
|
VRM is the Version Release Modification, for example, you can specify 520 to represent version 5.2.0.
x is a one-character suffix that specifies:
n
|
B—Cursor queries/updates with hold
|
n
|
C—Stored procedures (section 1 is for stored procedures that do not have parameters; section 2 is for procedures that do have parameters)
|
For example, the package name DDOC520A would represent a package using the Committed Read isolation level, at version 5.20, and using cursor queries/updates.
where xx is a two-character prefix.
where authid is a valid DB2 AuthID that has permissions to execute all the SQL in the package.
The password that the application uses to connect to your database. The Password option cannot be specified through the driver Setup dialog box and should not be stored in a data source. It is specified through the Logon dialog box or a connection string.
where pwd is a valid password.
Sets the Client Product Version/ID on the server. On DB2 for Linux/UNIX/Windows V9.1 and higher, this value is located in the CLIENT_PRDID column of the SYSIBMADM.APPLICATIONS table.
DDT identifies a DataDirect Connect driver.
VV identifies a 2-digit version number (with high-order 0 in the case of a 1-digit version).
RR identifies a 2-digit release number (with high-order 0 in the case of a 1-digit release).
M identifies a 1-character modification level (0-9 or A-Z).
The number of seconds for the default query timeout for all statements that are created by a connection. To override the value set by this connection option for an individual statement, set a different value in the SQL_ATTR_QUERY_TIMEOUT statement attribute.
where x is a positive integer representing the number of seconds.
If set to -1, the query does not time out. The driver silently ignores the SQL_ATTR_QUERY_TIMEOUT attribute on the SQLSetStmtAttr() function.
If set to 0, the query does not time out, but the driver responds to the SQL_ATTR_QUERY_TIMEOUT attribute on the SQLSetStmtAttr() function.
If set to x, all queries time out after the specified number of seconds unless the application overrides this value by setting the SQL_ATTR_QUERY_TIMEOUT attribute on the SQLSetStmtAttr() function.
Specifies how the driver handles code page conversion errors that occur when a character cannot be converted from one character set to another.
An error message or warning can occur if an ODBC call causes a conversion error, or if an error occurs during code page conversions to and from the database or to and from the application. The error or warning generated is
Code page conversion error encountered. In the case of parameter data conversion errors, the driver adds the following sentence:
Error in parameter x, where
x is the parameter number. The standard rules for returning specific row and column errors for bulk operations apply.
If set to 0 (Ignore Errors), the driver substitutes 0x1A for each character that cannot be converted and does not return a warning or error.
On DB2 for iSeries only, execute NETSTAT from a command line to determine the correct port number. Select option 3 to display a list of active ports on the iSeries machine. Find the entry for DRDA, and press F14 to toggle and display the port number. If DRDA is not currently listening, the command
CHGDDMTCPA AUTOSTART(*YES) PWDRQD(*YES) starts the listener and ensures that it is active at IPL.
IP_address |
service_name
IP_address is the port’s IP address.
service_name is the port’s service name. The driver must be able to find this name (with the correct port assignment) in the SERVICES file on the workstation.
The directory of the location of the truststore file to be used when SSL is enabled (Encryption Method=1) and server authentication is used. The truststore file contains a list of the valid Certificate Authorities (CAs) that are trusted by the client machine for SSL server authentication.
where truststore_directory is the directory where the truststore file is located.
The password that is used to access the truststore file when SSL is enabled (Encryption Method=1) and server authentication is used. The truststore file contains a list of the Certificate Authorities (CAs) that the client trusts.
where truststore_password is a valid password for the truststore file.
Specifies whether results are restricted to the tables and views in the current schema if a catalog function call is made without specifying a schema or if the schema is specified as the wildcard character %. Restricting results to the tables and views in the current schema improves performance of catalog calls that do not specify a schema.
The default user ID that is used to connect to your database. Your ODBC application may override this value or you may override it in the logon dialog box or connection string.
where userid is a valid user ID with permissions to access the database.
Determines whether the driver validates the certificate that is sent by the database server when SSL encryption is enabled (Encryption Method=1). When using SSL server authentication, any certificate sent by the server must be issued by a trusted Certificate Authority (CA). Allowing the driver to trust any certificate returned from the server even if the issuer is not a trusted CA is useful in test environments because it eliminates the need to specify truststore information on each client in the test environment.
If set to 1 (Enabled), the driver validates the certificate that is sent by the database server. Any certificate from the server must be issued by a trusted CA in the truststore file. If the Host Name In Certificate option is specified, the driver also validates the certificate using a host name. The Host Name In Certificate option provides additional security against man-in-the-middle (MITM) attacks by ensuring that the server the driver is connecting to is the server that was requested.
If set to 0 (Disabled), the driver does not validate the certificate that is sent by the database server. The driver ignores any truststore information specified by the Trust Store and Trust Store Password options.
If set to 1 (Enabled), cursor behavior is Preserve, which keeps cursors open after a commit or rollback (SQLGetInfo( ) returns SQL_CB_PRESERVE for SQL_COMMIT_CURSOR_BEHAVIOR).
If set to 0 (Disabled), cursor behavior is Delete, which closes all cursors open after a commit or rollback (SQLGetInfo( ) returns SQL_CB_DELETE).
See “Using the XML Data Type” for further information about the XML data type.
If set to -4 (SQL_LONGVARBINARY), the driver uses the description SQL_LONGVARBINARY for columns that are defined as the XML data type.
If set to -10 (SQL_WLONGVARCHAR), the driver uses the description SQL_WLONGVARCHAR for columns that are defined as the XML data type.