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 7-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 7-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 an Oracle 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.
- Optionally, click the Performance tab to specify performance data source settings.
- Optionally, click the Failover tab to specify 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 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 by default.
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.
Data Source Name: Type a string that identifies this Oracle data source configuration. Examples include Accounting or Oracle-Serv1.
Description: Type an optional long description of a data source name. For example, My Accounting Database or Oracle on Server number 1.
Server Name: Type the client connection string of the computer containing the Oracle database tables you want to access.
For local servers, use the SQL*Net connection string. If the SQL*Net connection string contains semicolons, enclose it in quotation marks. Refer to your SQL*Net documentation for more information.
For remote servers, the Oracle TNS Client connection string is the alias name of the Oracle Listener on your network.
Client Version: Select an Oracle client software version from the Client Version drop-down list. The driver assumes that it is using the version of Oracle client software specified by this option to connect to an Oracle server.
When set to 10gR1 and later, the driver binds all non-integer numerics as BINARY FLOAT and BINARY DOUBLE. When set to any Oracle version previous to Oracle10g R1, the driver binds non-integer numerics as if connected to an Oracle 9i R2 or earlier version of the server (regardless of the actual version of the server to which it is connected). When connecting to an Oracle 10g server with a pre-10g client, this attribute must be set to the same version as the actual Oracle client software in use; otherwise, numeric parameter bindings may fail. Versions of the Oracle client software prior to 10g R1 do not fully support the new features of the Oracle 10g database server. The default is 9i R1.
On this tab, provide any of the following optional information; then, click Apply.
Server List: Type a list of client connection strings that will appear in the logon dialog box. Separate the strings with commas. If the client connection string contains a comma, enclose it in quotation marks, for example, "Serv,1", "Serv,2", "Serv,3."
Default User Name: Type the default user ID used to connect to your Oracle database. A default user name is required only if security is enabled on your database. Your ODBC application may override this value or you may override this value in the logon dialog box or connection string.
The equivalent connection string attribute is LogonID.
You can also use OS Authentication to connect to your Oracle database. See "OS Authentication" for details.
Local Timezone Offset: Type a value to alter local time zone information. The default is "" (empty string), which means that, on Windows, the driver determines local time zone information from the operating system. If it is not available from the operating system, the driver defaults to using the setting on the Oracle server.
Valid values are specified as offsets from GMT as in: (-)HH:MM. For example, -08:00 equals GMT minus 8 hours. The driver uses the value of the option to issue an ALTER SESSION for the local time zone at connect time.
Enable Timestamp with Timezone: Select this check box to expose timestamps with timezones to the application. By default, the check box is not selected.
When selected, the driver issues an ALTER SESSION at connection time to modify NLS_TIMESTAMP_TZ_FORMAT. NLS_TIMESTAMP_TZ_FORMAT is changed to the ODBC definition of a timestamp literal with the addition of the timezone literal: 'YYYY-MM-DD HH24:MI:SSXFF TZR'.
Default Buffer Size for Long/LOB Columns (in Kb): Type an integer factor value that calculates the maximum length of data fetched from Long/LOB columns. The value must be in multiples of 1024 (for example, 1024, 2048). The default is 1024 KB. You need to increase the default value if the total size of any Long data exceeds 1 MB. This value is multiplied by 1024 to determine the total maximum length of fetched data. For example, if you enter a value of 2048, the maximum length of data would be 1024 x 2048, or 2097152 (2 MB).
This option also applies to binding Long parameters in chunks. The driver truncates any data passed in a Long/LOB SQL_DATA_AT_EXEC parameter to the size specified.
NOTE: This option is ignored if the Optimize Long Performance option is enabled.
This connection option can affect performance. See "Performance Considerations" for details.
The equivalent connection string attribute is DefaultLongDataBuffLen.
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.
IANAAppCodePage: For a list of valid values for this option, refer to "Values for the Attribute IANAAppCodePage" in the DataDirect Connect64 for ODBC and Connect64 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 Connect64 for ODBC and Connect64 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).
Catalog Options: Select this check box if you want the result column REMARKS (for the catalog functions SQLTables and SQLColumns) and the result column COLUMN_DEF (for the catalog function SQLColumns) to return actual values. Selecting this check box reduces the performance of your queries.
By default, the check box is not selected, which returns SQL_NULL_DATA for the result columns REMARKS and COLUMN_DEF.
This connection option can affect performance. See "Performance Considerations" for details.
Enable SQLDescribeParam: Select this check box to enable the SQLDescribeParam function, which results in all parameters being described with a data type of SQL_VARCHAR for Select statements. For Insert/Update/Delete statements and for stored procedures, the parameters are described as the actual Oracle data types on the Oracle server. This option must be selected to access data when using Microsoft Remote Data Objects (RDO). By default, the check box is not selected.
The equivalent connection string attribute is EnableDescribeParam.
Procedure Returns Results: Select this check box to enable the driver to return result sets from stored procedures/functions. See "Stored Procedure Results" for details. If this check box is selected and you execute a stored procedure that does not return result sets, you will incur a small performance penalty. By default, the check box is not selected.
This connection option can affect performance. See "Performance Considerations" for details.
The equivalent connection string attribute is ProcedureRetResults.
Describe at Prepare: Select this check box to cause the driver to describe the SQL statement at prepare time. By default, the check box is not selected.
This connection option can affect performance. See "Performance Considerations" for details.
Enable N-CHAR Support: Select this check box to enable support for the N-types NCHAR, NVARCHAR2, and NCLOB.
When this option is enabled, these types are described as SQL_WCHAR, SQL_WVARCHAR, and SQL_WLONGVARCHAR, and are returned as supported by SQLGetTypeInfo. In addition, the "normal" char types (CHAR, VARCHAR2, LONG, CLOB) are described as SQL_CHAR, SQL_VARCHAR, and SQL_LONGVARCHAR regardless of the character set on the Oracle server. By default, the check box is not selected.
See "Unicode Support" for details.
NOTE: Valid only on Oracle 9i and higher.
Report Recycle Bin: Select this check box to enable support for reporting objects that are in the Oracle Recycle Bin. By default, the check box is not selected.
On Oracle 10g R1 and higher, when a table is dropped, it is not actually removed from the database, but placed in the recycle bin instead. The driver does not normally report tables in the recycle bin because such tables are not intended for use by applications.
By default, the driver does not return tables contained in the recycle bin in the result sets returned from SQLTables and SQLColumns when connected to Oracle 10g R1 or higher. Functionally, this means that the driver filters out any results whose table name begins with BIN$.
The equivalent connection string attribute is ReportRecycleBin.
Timestamp Escape Mapping: Select how the driver maps Date, Time, and Timestamp literals.
When set to 0 - Oracle Version Specific (the default), the driver determines whether to use the TO_DATE or TO_TIMESTAMP function based on the version of the Oracle server to which it is connected.
When set to 1 - Oracle 8x Compatible, the driver always uses the Oracle 8.x TO_DATE function as if connected to an Oracle 8.x server.
When set to Oracle Version Specific, if the driver is connected to an 8.x server, it maps the Date, Time, and Timestamp literals to the TO_DATE function. If the driver is connected to an Oracle 9.x or higher server, it maps these escapes to the TO_TIMESTAMP function.
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.
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.
Array Size: Type the number of bytes the driver uses for fetching multiple rows. Values can be an integer from 1 to 4,294,967,296 (4 GB); the default is 60000. Larger values increase throughput by reducing the number of times the driver fetches data across the network. Smaller values increase response time, as there is less of a delay waiting for the server to transmit data.
The value 1 is a special value that does not define the number of bytes but, instead, causes the driver to allocate space for exactly one row of data.
This connection option can affect performance. See "Performance Considerations" for details.
Lock Timeout: Type 0, -1, or any integer value greater than 0. The value 0 specifies that Oracle does not wait for a lock to be freed before raising an error when processing a Select...For Update statement. The value -1 (the default) causes the server to wait indefinitely. When connected to an Oracle 9i or higher server, you can specify the number of seconds to wait by setting this option to an integer greater than 0. If you are connected to an Oracle 8i server, any value greater than 0 is equivalent to the value -1.
This connection option can affect performance. See "Performance Considerations" for details.
Use Current Schema for SQLProcedures: Select this check box to specify that the driver return only procedures owned by the current user when executing SQLProcedures. When this check box is selected (the default), the call for SQLProcedures is optimized, but only procedures owned by the user are returned.
This connection option can affect performance. See "Performance Considerations" for details.
The equivalent connection string attribute is UseCurrentSchema.
Catalog Functions Include Synonyms: Select this check box to include synonyms in calls to SQLProcedures, SQLStatistics, and SQLProcedureColumns. Clear the check box to exclude synonyms (a non-standard behavior) and, thereby, improve performance. By default, the check box is selected.
This connection option can affect performance. See "Performance Considerations" for details.
The equivalent connection string attribute is CatalogIncludesSynonyms.
Enable Scrollable Cursors: Select this check box to enable scrollable cursors for the data source. Both Keyset and Static cursors are enabled. By default, the check box is selected.
Enable Static Cursors for Long Data: Select this check box to enable the driver to support Long columns when using a static cursor. Selecting this check box causes a performance penalty at the time of execution when reading Long data. By default, the check box is not selected.
NOTE: You must select this check box if you want to persist a result set that contains Long data into an XML data file.
This connection option can affect performance. See "Performance Considerations" for details.
The equivalent connection string attribute is EnableStaticCursorsForLongData.
Optimize Long Performance: Select this check box to fetch Long data directly into the application's buffers rather than allocating buffers and making a copy. This option, when enabled, decreases fetch times on Long data; however, it can cause the application to be limited to one active statement per connection. By default, the check box is not selected.
NOTE: If this option is enabled, the Default Buffer Size for Long/LOB Columns (DefaultLongDataBuffLen) option is ignored.
This connection option can affect performance. See "Performance Considerations" for details.
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 Oracle driver, you must specify the server name. The string has the format:
(ServerName=servervalue[, . . .])
For example, the following Alternate Servers value defines two alternate database servers for connection failover:
(ServerName=AcctBackup1, ServerName=AcctBackup2)
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.
Verify that all required client software is properly installed. If it is not, you will see the message:
Specified driver could not be loaded due to system error [xxx].
Click OK.
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.