After you install the driver, you configure data sources to connect to the database. See Chapter 1 “Quick Start Connect” for an explanation of different types of data sources. The data source contains connection options that allow you to tune the driver for specific performance. If you want to use a data source but need to change some of its values, you can either modify the data source or override its values at connection time through a connection string.
If you choose to use a connection string, you must use specific connection string attributes. See “Using a Connection String” and Table 5-1 for an alphabetical list of driver connection string attributes and their initial default values.
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 for UNIX and Linux are stored in the system information file (by default, odbc.ini). If you have a Motif GUI environment on Linux, you can configure and modify data sources through the DataDirect ODBC Data Source Administrator for Linux (the Linux ODBC Administrator) using a driver Setup dialog box. (See “Configuration Through the 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 odbc.ini file and storing default connection values there. See “Configuration Through the System Information (odbc.ini) File” for detailed information about the specific steps necessary to configure a data source.
Table 5-1 lists driver connection string attributes that must be used in the odbc.ini file to set the value of the attributes. Note that only the long name of the attribute can be used in the file. The default listed in the table is the initial default value when the driver is installed.
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 this section.
On UNIX and Linux, data sources are stored in the odbc.ini file. On Linux, you can configure and modify data sources through the Linux ODBC Administrator using a driver Setup dialog box, as described in this section.
NOTE: This book shows dialog box images that are specific to Windows. If you are using the drivers in the Linux environment, 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.
When the driver is first installed, the values of its connection options are set by default. These values appear on the driver Setup dialog box tabs when you create a new data source. You can change these default values by modifying the data source. In the following procedure, the description of each tab is followed by a table that lists the connection options for that tab and their initial default values. This table links you to a complete description of the options and their connection string attribute equivalents. The connection string attributes are used to override the default values of the data source if you want to change these values at connection time.
|
■
|
On Windows, start the ODBC Administrator by selecting its icon from the DataDirect Connect program group.
|
|
■
|
On Linux, change to the install_dir/tools directory and, at a command prompt, enter:
|
where install_dir is the path to the product installation directory.
|
■
|
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.
|
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.
|
■
|
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.
|
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.
|
■
|
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.
|
If you are configuring a new file data source, click Add to display a list of installed drivers; then, select a driver. Click Advanced if you want 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.
NOTE: The General tab displays only fields that are required for creating a data source. The fields on all other tabs are optional, unless noted otherwise.
|
3
|
On this tab, provide values for the options in the following table; then, click Apply. The table provides links to descriptions of the connection options.
|
|
4
|
Optionally, click the Advanced tab to specify additional data source settings.
|
On this tab, provide values for any of the options in the following table; then, click Apply. The table provides links to descriptions of the connection options.
|
IANAAppCodePage
UNIX ONLY |
Translate: Click Translate to display the Select Translator dialog box, which lists the translators specified in the ODBC Translators section of the Registry. Progress 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.
|
5
|
Optionally, click the Security tab to specify security data source settings.
|
See “Using Security” for a general description of authentication and encryption and their configuration requirements.
On this tab, provide values for any of the options in the following table; then, click Apply. The table provides links to descriptions of the connection options.
|
6
|
Optionally, click the Modify Bindings tab to configure options for creating or modifying bind packages.
|
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 box. 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 values for any of the options in the following table; then, click Apply. The table provides links to descriptions of the connection options.
|
7
|
Optionally, click the Failover tab to specify failover data source settings.
|
See “Using Failover” for a general description of failover and its related connection options.
On this tab, provide values for any of the options in the following table; then, click Apply. The table provides links to descriptions of the connection options.
|
8
|
Optionally, click the Pooling tab to specify connection pooling data source settings.
|
See “Using DataDirect Connection Pooling” for a general description of connection pooling.
On this tab, provide values for any of the options in the following table; then, click Apply. The table provides links to descriptions of the connection options.
|
9
|
Optionally, click the Bulk tab to specify DataDirect Bulk Load data source settings.
|
See “Using DataDirect Bulk Load” for a general description of DataDirect Bulk Load.
On this tab, provide values for any of the options in the following table; then, click Apply. The table provides links to descriptions of the connection options.
If your application is already coded to use parameter array batch functionality, you can leverage DataDirect Bulk Load features through the Enable Bulk Load connection option. Enabling this option automatically converts the parameter array batch operation to use the database bulk load protocol.
If you are not using parameter array batch functionality, you can export data to a bulk load data file, verify the metadata of the bulk load configuration file against the structure of the target table, and bulk load data to a table. Use the following steps to accomplish these tasks.
|
a
|
To export data from a table to a bulk load data file, click Export Table from the Bulk tab. The Export Table dialog box appears.
|
Both a bulk data file and a bulk configuration file are produced by exporting a table. The configuration file has the same name as the data file, but with an XML extension. See “Using DataDirect Bulk Load” for details about these files.
The bulk export operation can create a log file and can also export to external files. See “External Overflow Files” for more information. The export operation can be configured such that if any errors or warnings occur:
Table Name: A string that specifies the name of the source database table containing the data to be exported.
Export Filename: A string that specifies the path (relative or absolute) and file of the bulk load data file to which the data is to be exported. It also specifies the file name of the bulk configuration file. These files must not already exist; if one of both of them already exists, an error is returned.
Log Filename: A string that specifies the path (relative or absolute) and file name of the bulk log file. The log file is created if it does not exist. Events logged to this file are:
Information about the load is written to this file, preceded by a header. Information about the next load is appended to the end of the file.
Error Tolerance: A value that specifies the number of errors to tolerate before an operation terminates. A value of 0 indicates that no errors are tolerated; the operation fails when the first error is encountered.
Warning Tolerance: A value that specifies the number of warnings to tolerate before an operation terminates. A value of 0 indicates that no warnings are tolerated; the operation fails when the first warning is encountered.
Code Page: A value that specifies the code page value to which the driver must convert all data for storage in the bulk data file. See “Character Set Conversions” for more information.
The default value on Windows is the current code page of the machine. On UNIX/Linux, the default value is 4 (ISO 8559-1 Latin-1).
Click Export Table to connect to the database and export data to the bulk data file or click Cancel.
To verify the metadata of the bulk load configuration file against the structure of the target database table, click Verify from the Bulk tab. See “Verification of the Bulk Load Configuration File” for details. The Verify dialog box appears.
Table Name: A string that specifies the name of the target database table into which the data is to be loaded.
Configuration Filename: A string that specifies the path (relative or absolute) and file name of the bulk configuration file.
|
b
|
To bulk load data from the bulk data file to a database table, click Load Table from the Bulk tab. The Load File dialog box appears.
|
The load operation can create a log file and can also create a discard file that contains rows rejected during the load. The discard file is in the same format as the bulk load data file. After fixing reported issues in the discard file, the bulk load can be reissued using the discard file as the bulk load data file.
If a load fails, the Load Start and Load Count options can be used to control which rows are loaded when a load is restarted after a failure.
Table Name: A string that specifies the name of the target database table into which the data is loaded.
Load Data Filename: A string that specifies the path (relative or absolute) and file name of the bulk data file from which the data is loaded.
Configuration Filename: A string that specifies the path (relative or absolute) and file name of the bulk configuration file.
Log Filename: A string that specifies the path (relative or absolute) and file name of the bulk log file. Specifying a value for Log Filename creates the file if it does not already exist. Events logged to this file are:
Information about the load is written to this file, preceded by a header. Information about the next load is appended to the end of the file.
Discard Filename: A string that specifies the path (relative or absolute) and file name of the bulk discard file. Any row that cannot be inserted into database as result of bulk load is added to this file, with the last row rejected added to the end of the file.
Information about the load is written to this file, preceded by a header. Information about the next load is appended to the end of the file.
Error Tolerance: A value that specifies the number of errors to tolerate before an operation terminates. A value of 0 indicates that no errors are tolerated; the operation fails when the first error is encountered.
Load Start: A value that specifies the first row to be loaded from the data file. Rows are numbered starting with 1. For example, when Load Start is 10, the first 9 rows of the file are skipped and the first row loaded is row 10. This option can be used to restart a load after a failure.
Read Buffer Size (KB): A value that specifies the size, in KB, of the buffer that is used to read the bulk data file for a bulk load operation.
Warning Tolerance: A value that specifies the number of warnings to tolerate before an operation terminates. A value of 0 indicates that no warnings are tolerated; the operation fails when the first warning is encountered.
Load Count: A value that specifies the number of rows to be loaded from the data file. The bulk load operation loads rows up to the value of Load Count from the file to the database. It is valid for Load Count to specify more rows than exist in the data file. The bulk load operation completes successfully when either the number of rows specified by the Load Count value has been loaded or the end of the data file is reached. This option can be used in conjunction with Load Start to restart a load after a failure.
Optionally, click the Client Monitoring tab to specify additional data source settings.
See “Using Client Information” for additional information about client monitoring.
On this tab, provide values for any of the options in the following table; then, click Apply. The table provides links to descriptions of the connection options.
|
10
|
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 “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 Established message. Click OK.
|
|
■
|
If the driver cannot connect because of an incorrect environment or connection value, it displays an appropriate error message. Click OK.
|
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.
|
11
|
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 want to use a connection string for connecting to a database, or if your application requires it, you must specify either a DSN (data source name), a File DSN, or a DSN-less connection in the string. The difference is whether you use the DSN=, FILEDSN=, or the DRIVER= keyword in the connection string, as described in the ODBC specification. A DSN or FILEDSN connection string tells the driver where to find the default connection information. Optionally, you may specify attribute=value pairs in the connection string to override the default values stored in the data source.
The DSN-less connection string specifies a driver instead of a data source. All connection information must be entered in the connection string because the information is not stored in a data source.
Table 5-1 lists the long and short names for each attribute, as well as the initial default value when the driver is first installed. You can specify either long or short names in the connection string.
An example of a DSN connection string with overriding attribute values for DB2 for Linux/UNIX/Windows is:
Some ODBC applications display a logon dialog box when you are connecting to a data source. In these cases, the data source name has already been specified.
|
1
|
In the Ip Address field, type the IP (Internet Protocol) address of the machine where the catalog tables are stored. Specify the address using the machine's numeric address (for example, 123.456.78.90) 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 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.
|
2
|
In the Tcp Port field, type the port number that is assigned to the DB2 server on the machine where the catalog tables are stored. Specify either this port's numeric address or its service name (50000 is the default port address). If you specify a service name, the driver must find this name (with the correct port assignment) in the SERVICES file on the workstation.
|
|
3
|
If you are running DB2 for z/OS or iSeries, perform Steps 3a and 3b. Otherwise, skip to Step 4.
|
|
a
|
In the Location field, type the DB2 location name. Use the name defined during the local DB2 installation.
|
|
b
|
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 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. On iSeries only, Collection is also the current library.
|
4
|
If you are running DB2 for Linux/UNIX/Windows, type the name of the database to which you want to connect in the Database field.
|
|
7
|
Click OK to complete the logon and to update the values in the Registry.
|