Configuring Data Sources
After you install the driver, you need to configure a data source or use a connection string to connect to the database. If you want to use a data source, but need to change some of its values, you can either modify it or override its values through a connection string. See "Quick Start Connect" for an explanation of different types of data sources.
If you choose to use a connection string, you must use specific connection string attributes. See "Connecting to a Data Source Using a Connection String" and Table 4-1 for a complete description of driver connection string attributes and their values.
UNIX
On UNIX and Linux, you must set up the proper ODBC environment before configuring data sources. See "Environment Configuration" for basic setup information and "Environment Variables" for more detail about this procedure.
Data sources are stored in the system information file (by default, odbc.ini). If you have a Motif GUI environment on UNIX or Linux, you can configure and modify data sources through the DataDirect ODBC Data Source Administrator for UNIX/Linux (the UNIX ODBC Administrator) using a driver Setup dialog box, as described in the following procedure. (See "Configuration Through the UNIX ODBC Administrator" for a detailed explanation of the Administrator.)
If you do not have a GUI environment, you can configure and modify data sources directly by editing the system information file and storing default connection values there. See "Configuration Through the System Information File" for detailed information about the specific steps necessary to configure a data source.
Table 4-1 lists driver connection string attributes that must be used in the system information file. Note that only the long name of the attribute can be used in the file.
Windows
On Windows, data sources are stored in the Windows Registry. You can configure and modify data sources through the ODBC Administrator using a driver Setup dialog box, as described in the following section.
Configuration
Default connection values are specified through the options on the tabs of the Setup dialog box. Connection string attributes that override these options have the same names as the options unless noted otherwise. The connection string attribute name does not have spaces between the words. For example, the option name Application Using Threads is equivalent to the connection string attribute name ApplicationUsingThreads.
NOTE: This book shows dialog box images that are specific to Windows. If you are using the drivers in the UNIX/Linux environments, the dialog box that you see may differ slightly from the Windows version. Windows-only and UNIX-only connection options are specifically noted by icons in the Setup dialog box descriptions.
By default, edit boxes and drop-down lists on the Setup dialog box are empty unless a specific default is otherwise noted.
To configure a DB2 data source:
- Start the ODBC Administrator:
- Select a tab:
- User DSN: If you are configuring an existing user data source, select the data source name and click Configure to display the driver Setup dialog box.
System DSN: If you are configuring an existing system data source, select the data source name and click Configure to display the driver Setup dialog box.- File DSN: If you are configuring an existing file data source, select the data source file and click Configure to display the driver Setup dialog box.
- On the General tab, provide the following information; then, click Apply.
- Optionally, click the Advanced tab to specify additional data source settings.
- 0 - READ_UNCOMMITTED-Allows other processes to read from the database. Only modified data is locked until the end of the transaction.
- 1 - READ_COMMITTED (the default)-Allows other processes to change a row that your application has read if the cursor is not on the row you want to change. It prevents other processes from changing records that your application has changed until your program commits them or terminates. It prevents your program from reading a modified record that has not been committed by another process.
- 2 - REPEATABLE_READ-Prevents any other process from accessing data that your application has read or modified. All read or modified data is locked until the end of the transaction.
- 3 - SERIALIZABLE-Prevents other processes from changing records that are read or changed by your application (including phantom records) until your program commits them or terminates. It prevents the application from reading modified records that have not been committed by another process. If your program 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 program.
- 4 - NONE-Allows your program to read modified records even if they have not been committed by another user. This level can only be set in the data source, not from the application. (This level is valid only on iSeries, and is the only isolation level that works for collections that have journaling enabled.)
- Optionally, click the Security tab to specify security data source settings.
- Optionally, click the Modify Bindings tab to configure options for creating or modifying bind packages.
- Optionally, click the Failover tab to specify connection failover data source settings.
- At any point during the configuration process, you can click Test Connect to attempt to connect to the data source using the connection options specified in the driver Setup dialog box. A logon dialog box appears (see "Connecting to a Data Source Using a Logon Dialog Box" for details). Note that the information you enter in the logon dialog box during a test connect is not saved.
- If the driver can connect, it releases the connection and displays a
Connection Establishedmessage. Click OK. - If the driver cannot connect because of an incorrect environment or connection value, it displays an appropriate error message. Click OK.
- Click OK or Cancel. If you click OK, the values you have specified become the defaults when you connect to the data source. You can change these defaults by using this procedure to reconfigure your data source. You can override these defaults by connecting to the data source using a connection string with alternate values.
If you are configuring a new user data source, click Add to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.
If you are configuring a new system data source, click Add to display a list of installed drivers. Select the driver and click Finish to display the driver Setup dialog box.
If you are configuring a new file data source, click Add to display a list of installed drivers. Select the driver and click Advanced to specify attributes; otherwise, click Next to proceed. Specify a name for the data source and click Next. Verify the data source information; then, click Finish to display the driver Setup dialog box.
The General tab of the Setup dialog box appears.
NOTE: Fields on the General tab are required for creating a data source. The fields on all other tabs are optional, unless noted otherwise in this book.
Data Source Name: Type a string that identifies this DB2 data source configuration. Examples include Accounting or DB2-Serv1.
Description: Type an optional long description of a data source name. For example, My Accounting Database or DB2 files on Server number 1.
Ip Address: Type the IP (Internet Protocol) address of the machine where the catalog tables are stored. Specify the address using the machine's numeric address or specify its host name. If you enter a host name, the driver must find this name (with the correct address assignment) in the HOSTS file on the workstation or in a DNS server. The default is localhost.
The numeric IP address can be specified in either IPv4 or IPv6 format, or a combination of the two. See "Using IP Addresses" for details concerning these formats.
Tcp Port: Type the port number that is assigned to the DB2 DRDA listener process on the server host machine. Specify either this port's numeric address or its service name. If you specify a service name, the driver must find this name (with the correct port assignment) in the SERVICES file on the workstation. The default is 50000.
On DB2 for iSeries only, execute NETSTAT from an iSeries 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 iSeries command CHGDDMTCPA AUTOSTART(*YES) PWDRQD(*YES) starts the listener and ensures that it is active at IPL.
Location Name: This field is valid and required only if you are connecting to a DB2 database for z/OS or iSeries. Type the DB2 location name. Use the name defined during the local DB2 installation.
On DB2 for z/OS only, your system administrator can determine the name of your DB2 location using the DISPLAY DDF command.
On DB2 for iSeries only, 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 you should use.
NOTE: This field is disabled if you specified a value in the Database Name field.
The equivalent connection string attribute is Location.
Collection: This field is valid only if you are connecting to DB2 for z/OS or iSeries. By default, the User ID is used for the value of Collection. The User ID must always be used on DB2 for z/OS.
On DB2 for iSeries, you can type the name of the schema that is to be the default qualifier for unqualified object names. If you want to access a table outside of this schema, you need to specify the appropriate two-part name, for example:
SELECT * FROM Schema.Tablename
Collection is also the current library. 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 is not valid for DB2 V5R1 for iSeries.) Collection is overridden by Alternate ID on iSeries if a value is set for Alternate ID.
NOTE: This field is disabled if you specified a value in the Database Name field.
Database Name: This field is valid and required only if you are connecting to DB2 for Linux/UNIX/Windows. Type the name of the database to which you want to connect.
NOTE: This field is disabled if you specified a value in the Location Name or Collection fields.
The equivalent connection string attribute is Database.
On this tab, provide any of the following optional information; then, click Apply.
Add to Create Table: Type a string that is automatically added to all Create Table statements. This field is primarily for users who need to add an "in database" clause.
The equivalent connection string attribute is AddStringToCreateTable.
Alternate ID: Type the default qualifier for unqualified object names in SQL statements that will be substituted at connect time for the current schema. This sets the default qualifier for unqualified object names in 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 is not valid for DB2 V5R1 for iSeries.)
Catalog Schema: Type the DB2 schema to use for Catalog functions. The value must be the name of a valid DB2 schema. If you do not specify a value, the driver uses SYSIBM when connected to DB2 for z/OS, QSYS2 when connected to DB2 for iSeries, and SYSCAT when connected to DB2 for Linux/UNIX/Windows.
Default Isolation Level: Select the method by which locks are acquired and released by the system (Refer to "Locking and Isolation Levels" in the DataDirect Connect for ODBC and Connect XE for ODBC Reference for details about ODBC isolation levels).
ODBC isolation levels map to DB2 isolation levels as follows:
|
ODBC
|
DB2
|
|---|---|
|
Read Uncommitted
|
Uncommitted Read
|
|
Read Committed
|
Cursor Stability
|
|
Repeatable Read
|
Read Stability
|
|
Serializable
|
Repeatable Read
|
Valid values are:
Character Set for CCSID 65535: This option specifies a character set from which to convert when fetching character columns (char, varchar, longvarchar, clob, char for bit data, varchar for bit data, longvarchar for bit data) defined with Coded Character Set Identifier (CCSID) 65535.
If you do not specify a value, the driver returns these columns as binary columns (SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY) and does no conversion of the data.
When you specify any valid IANA code page value, the driver returns these columns as character columns and assumes they are being returned in the character set specified. The driver does no conversion of data supplied in bound parameters. See "IBM to IANA Code Page Values" for a table of IANA and IBM code page equivalents.
NOTE: All columns defined as Char for Bit Data, Varchar for Bit Data, and Longvarchar for Bit Data are affected by this option. By definition, columns created with these types have a CCSID of 65535.
The equivalent connection string attribute is CharsetFor65535.
Report Codepage Conversion Errors: Select the method by which the driver handles code page conversion errors.
When set to 0 - Ignore Errors (the default), if the driver encounters code page conversion errors (a character cannot be converted from one character set to another), it makes a substitution for each character that cannot be converted and does not return a warning or error.
Error and Warning apply both to all ODBC API calls that could cause a conversion error and to all code page conversions to and from the database and to and from the application. The error or warning returned 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 still apply.
When set to 1 - Return Error, if the driver encounters code page conversion errors, it returns an error instead of substituting 0x1A for unconverted characters.
When set to 2 - Return Warning, if the driver encounters code page conversion errors, it substitutes 0x1A for each character that cannot be converted and returns a warning.
Application Using Threads: Select this check box to ensure that the driver works with multi-threaded applications. You can clear this check box when using the driver with single-threaded applications. Turning off this setting avoids additional processing required for ODBC thread-safety standards. By default, the check box is selected.
This connection option can affect performance. See "Performance Considerations" for details.
Use Current Schema for Catalog Functions: Select this check box to specify whether results are restricted to the tables in the current schema if a catalog function call is made either without specifying a schema or specifying the schema as the wildcard character %. Restricting results to tables in the current schema improves the performance of calls that do not specify a schema.
If this check box is not selected (the default), the results of catalog function calls are not restricted.
The equivalent connection string attribute is UseCurrentSchema.
This connection option can affect performance. See "Performance Considerations" for details.
With Hold Cursors: Select this check box to specify the cursor behavior for the application used with this data source-either DB2 closes all open cursors after a commit or rollback (Delete cursors) or leaves them open (Preserve cursors).
When this check box is selected (the default), the cursor behavior is Preserve (SQLGetInfo( ) returns SQL_CB_PRESERVE for SQL_COMMIT_CURSOR_BEHAVIOR).
If the check box is not selected, the cursor behavior is Delete (SQLGetInfo( ) returns SQL_CB_DELETE). For information about this function, refer to the Microsoft ODBC API.
The equivalent connection string attribute is WithHold.
XML Describe Type: Select the SQL data type returned by SQLGetTypeInfo() for the XML data type.
When set to -4 - SQL_LONGVARBINARY, the driver uses the description SQL_LONGVARBINARY for columns defined as the DB2 XML data type.
When set to -10- SQL_WLONGVARCHAR (the default), the driver uses the description SQL_WLONGVARCHAR for columns defined as the DB2 XML data type.
See the "Using the XML Data Type" for further information about the XML data type.
IANAAppCodePage: For a list of valid values for this option, refer to "Values for the Attribute IANAAppCodePage" in the DataDirect Connect for ODBC and Connect XE for ODBC Reference. You need to specify a value for this option if your application is not Unicode-enabled and/or if your database character set is not Unicode (refer to "Internationalization, Localization, and Unicode" in the DataDirect Connect for ODBC and Connect XE for ODBC Reference for details). The value you specify must match the database character encoding and the system locale.
Both this driver and the Driver Manager check for the value of IANAAppCodePage in the following order:
If no IANAAppCodePage value is found, the driver uses the default value of 4 (ISO 8859-1 Latin-1).
Translate: Click Translate to display the Select Translator dialog box, which lists the translators specified in the ODBC Translators section of the Registry. DataDirect provides a translator named OEM to ANSI that translates your data from the IBM PC character set to the ANSI character set.
Select a translator; then, click OK to close this dialog box and perform the translation.
On this tab, provide any of the following optional information; then, click Apply.
See "Using Security" for a general description of authentication and encryption and their requirements.
User Name: Type the default user ID 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.
The equivalent connection string attribute is LogonID.
Authentication Method: Select the method the driver uses to authenticate the user to the server when a connection is established.
When set to 0 - No Encryption (the default), the driver sends the user ID and password in clear text to the server for authentication.
When set to 1 - Encrypt Password, the driver sends the user ID in clear text and an encrypted password to the server for authentication.
When set to 2 - Encrypt UID and Password, the driver sends an encrypted user ID and password to the server for authentication.
When set to 3 - Client, 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.
When set to 4 - Kerberos, the driver uses Kerberos authentication. This method supports both Windows Active Directory Kerberos and MIT Kerberos environments.
If the specified authentication method is not supported by the database server, the connection fails and the driver generates an error.
GSS Client Library: Type the name of the GSS client library that the driver uses to communicate with the Key Distribution Center (KDC). The default value is native, indicating that the driver uses the GSS client that ships with the operating system. The driver uses the standard path for loading the specified client library.
Encryption Method: Select the method the driver uses to encrypt data sent between the driver and the database server.
When set to 0 - No Encryption (the default), data is not encrypted.
When set to 1 - SSL, data is encrypted using SSL (supported only on DB2 for iSeries).
When 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).
NOTE: DB2 encryption protocol can only be specified when Authentication Method is set to 0, 1, or 2.
If the specified encryption method is not supported by the database server, the connection fails and the driver returns an error.
This connection option can affect performance. See "Performance Considerations" for details.
Validate Server Certificate: Select this check box (the default) to validate the security certificate of the server as part of the SSL authentication handshake.
When this check box is not selected, the driver does not validate the security certificate of the server.
Truststore: If you are using SSL, type the path that specifies the location of the truststore file. The truststore file contains a list of the valid Certificate Authorities (CAs) that are trusted by the client machine for SSL server authentication.
Truststore Password: If you are using SSL, type the password required to access the truststore.
Host Name In Certificate: Type the host name established by the SSL administrator for the driver to validate the host name contained in the certificate. If no value is specified for Host Name In Certificate, the driver does not check the host name in the server certificate. The value of Host Name In Certificate is ignored if Validate Server Certificate is not selected or if Encryption Method does not specify SSL.
If a value is specified for Host Name In Certificate, 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 the value specified for HostNameInCertificate is the special value #SERVERNAME#, then the driver compares the IP Address option value specified as part of a data source or connection string to the dnsName value or the commonName.
The Modify Bindings tab allows you to create or modify bind packages on the server accessed by the driver. If you connect with the driver before explicitly creating bind packages, the driver creates packages on the server automatically using the current values from the Setup dialog. Alternatively, you can create a bind package before testing the connection. You can also modify bind packages after their creation from the Modify Bindings tab. You must also provide appropriate values for the options on the General tab.
NOTE: If you change any of the values on this tab after having initially created bind packages, you must rebind the packages. The changes are reflected only on new connections after rebinding.
On this tab, provide the following information; then, click Apply.
Dynamic Sections: Type the number of SQL statements that the DB2 Wire Protocol driver package can prepare for a single user. The default is 200.
Package Collection: Type the collection or location name where the driver creates the bind packages and searches for them when required. The default is NULLID.
Package Owner: Type the AuthID assigned to the package. This DB2 AuthID must have authority to execute all the SQL in the package (optional).
Grant Execute to: Select this check box to grant EXECUTE privileges on the bind packages that you are creating. By default, the check box is selected and the schema to which privileges are granted is PUBLIC.
If you want to grant EXECUTE privileges to a different schema, type a schema name. It must be a valid DB2 schema.
When this check box is not selected, EXECUTE privileges are granted to the schema that created the DB2 packages.
The equivalent connection string attributes for specifying to whom privileges are granted are GrantExecute and GrantAuthid.
Modify Bindings: After you specify values for the options on the General and Modify Bindings tabs, click Modify Bindings to create or modify packages; a logon dialog box appears. Enter your user ID and password; then, click Login. If packages are created and bound successfully, a message indicating success appears. If problems occur when attempting to connect or create the packages, an appropriate error message is generated.
On this tab, provide any of the following optional information; then, click Apply.
Load Balancing: Select this check box to allow the driver to use client load balancing in its attempts to connect to primary and alternate database servers. In this case, the driver attempts to connect to the database servers in random order. See "Using Client Load Balancing" for more information.
If this check box is not selected (the default), client load balancing is not used and the driver connects to each database server based on its sequential order (primary server first, then, alternate servers in the order they are specified).
NOTE: This option has no effect unless alternate servers are defined for the Alternate Servers connection option.
The Load Balancing option is an optional setting that you can use in conjunction with connection failover. See "Configuring Connection Failover" for a discussion of connection failover and for information about other connection options that you can set for this feature.
Alternate Servers: Type 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. See "Using Connection Failover" for a discussion of connection failover.
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.
For the DB2 Wire Protocol driver, you must specify the IP address, port number, and database name (Linux/UNIX/Windows) or location (z/OS and iSeries) of each alternate server. The string has the format:
(IPAddress=ipvalue:TcpPort=portvalue:{Database | Location}=databasevalue[, . . .])
For example, the following Alternate Servers values define two alternate database servers for connection failover:
AlternateServers=(IpAddress=123.456.78.90:
TcpPort=5177:Database=DB2DAT, IpAddress=223.456.78.90:TcpPort=5178:Database=DB2DAT3)
or
AlternateServers=(IpAddress=123.456.78.90:
TcpPort=5177:Location=DB2DAT, IpAddress=223.456.78.90:TcpPort=5178:Location=DB2DAT3)
See "Configuring Connection Failover" for information about other connection options that you can set for this feature.
Connection Retry Count: Type a value to specify the number of times the driver tries to connect to the primary server and, if configured, to the alternate servers after the initial unsuccessful attempt. See "Using Connection Retry" for more information about this feature.
Valid values are integers from 0 to 65535. When set to 0 (the default), the driver does not try to connect after the initial unsuccessful attempt.
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.
This option and the Connection Retry Delay connection option, which specifies the wait interval between attempts, can be used in conjunction with connection failover.
See "Configuring Connection Failover" for a discussion of connection failover and for information about other connection options that you can set for this feature.
Connection Retry Delay: Type a value to specify the number of seconds that the driver waits after the initial unsuccessful connection attempt before retrying a connection to the primary server and, if specified, to the alternate servers.
Valid values are integers from 0 to 65535. The default value is 3 (seconds). When set to 0, there is no delay between retries.
NOTE: This option has no effect unless the Connection Retry Count connection option is set to an integer value greater than 0.
This option and the Connection Retry Count connection option, which specifies the number of times the driver tries to connect after the initial unsuccessful attempt, can be used in conjunction with connection failover.
See "Configuring Connection Failover" for a discussion of connection failover and for information about other connection options that you can set for this feature.
IMPORTANT: If you have not already created bind packages by clicking the Modify Bindings button on the Modify Bindings tab, the initial connection through the Test Connect button may take a few minutes because of the number and size of the packages that must be created on the server. Subsequent connections occur without this delay.
NOTE: If you are configuring alternate servers for use with the connection failover feature, be aware that the Test Connect button tests only the primary server, not the alternate servers.