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 6-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 6-1 lists the connection values, in the form of 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.
The following section offers two basic connection methods for configuring a data source, either of which you can use, but that are mutually exclusive.
In the first, you specify Host and Port number, and either SID or Service Name. You must use one or the other; entering a value for SID disables the Service Name field and vice versa. If you use this method, it also disables the Server Name and TNSNames File fields, as they are part of the second method.
Alternatively, the driver can obtain connection information from the TNSNAMES.ORA file. In this case, you enter values only in the Server Name and TNSNames File fields. Doing so disables the Host, Port number, SID, and Service Name fields.
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 Security tab to specify security 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.
- 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.
NOTE: If you want to configure a standard connection, complete only the following four fields.
Host: Type either the name or the IP address of the server to which you want to connect.
For example, if your network supports named servers, you can specify a server name such as Oracleserver. Or, you can specify an IP address such as 199.226.224.34.
If you enter a value for this field, the Server Name and TNSNames File fields are not available.
This field is not available if you enter a value for the Server Name or TNSNames File fields.
The equivalent connection string attribute is HostName.
Port Number: Type the port number of your Oracle listener. Check with your database administrator for the correct number.
If you enter a value for this field, the Server Name and TNSNames File fields are not available.
This field is not available if you enter a value for the Server Name or TNSNames File fields.
SID: Type the Oracle System Identifier that refers to the instance of Oracle running on the server.
If you enter a value for this field, the Service Name, Server Name, and TNSNames File fields are not available.
This field is not available if you enter a value for the Service Name, Server Name, or TNSNames File fields.
Service Name: Type the Oracle service name that specifies the database used for the connection. The service name is a string that is the global database name-a name that is comprised of the database name and domain name, for example:
sales.us.acme.com
The service name is included as part of the Oracle connect descriptor, which is a description of the destination for a network connection. The service name is specified in the CONNECT_DATA parameter of the connect descriptor, for example:
(CONNECT_DATA=(SERVICE_NAME=sales.us.acme.com))
In this example, you would specify sales.us.acme.com as the value for the Service Name connection option.
If you enter a value for this field, the SID, Server Name, and TNSNames File fields are not available.
This field is not available if you enter a value for the SID, Server Name, or TNSNames File fields.
NOTE: If you want to configure a TNSNames connection, complete only the following two fields.
Server Name: Type a net service name that exists in the TNSNAMES.ORA file. The corresponding net service name entry in the TNSNAMES.ORA file is used to obtain Host, Port Number, and Service Name or SID information.
If you enter a value for this field, the Host, Port Number, SID, and Service Name fields are not available.
If you enter a value for either the Host, Port Number, SID, or Service Name fields, this field is not available.
TNSNames File: Type the entire path, including the file name, to the TNSNAMES.ORA file. In a TNSNAMES.ORA file, connection information for Oracle services is associated with an Oracle net service name. The entry in the TNSNAMES.ORA file specifies Host, Port Number, and Service Name or SID.
TNSNames File is ignored if no value is specified in the Server Name option. If the Server Name option is specified but the TNSNames File option is left blank, the TNS_ADMIN environment setting is used for the TNSNAMES.ORA file path. If there is no TNS_ADMIN setting, the ORACLE_HOME environment setting is used. On Windows, if ORACLE_HOME is not set, the path is taken from the Oracle section of the Registry.
If you enter a value for this field, the Host, Port Number, SID, and Service Name fields are not available.
If you enter a value for either the Host, Port Number, SID, or Service Name fields, this field is not available.
Using an Oracle TNSNAMES.ORA file to centralize connection information in your Oracle environment simplifies maintenance when changes occur. If, however, the TNSNAMES.ORA file is unavailable, then it is useful to be able to open a backup version of the TNSNAMES.ORA file (TNSNames file failover). You can specify one or more backup, or alternate, TNSNAMES.ORA files.
To specify multiple TNSNAMES.ORA file locations, separate the names with a comma and enclose the locations in parentheses (you do not need parentheses for a single entry). For example:
(F:\server2\oracle\tnsnames.ora, C:\oracle\product\10.1\db_1\network\admin\tnsnames.ora)
The driver tries to open the first file in the list. If that file is not available, then it tries to open the second file in the list, and so on.
Connection Retry Count and Connection Retry Delay (see Step 7) are also valid with TNSNames failover. The driver makes at least one attempt to open the files, and, if Connection Retry Count is enabled, more than one. If Connection Retry Delay is enabled, the driver waits the specified number of seconds between attempts. Load Balancing is not available for TNSNames failover.
On this tab, provide any of the following optional information; then, click Apply.
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 follows: (-)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.
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 catalog (SQLColumns and SQLTables) 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 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 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 and higher. Functionally, this means that the driver filters out any results whose Table name begins with BIN$.
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 a 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.
Server Process Type: Select whether the connection is established using a shared or dedicated server process (dedicated thread on Windows).
If set to 0 - Server Default (the default), the driver uses the default server process set on the server.
NOTE: The server must be configured for shared connections (the SHARED_SERVERS initialization parameter on the server has a value greater than 0) for the driver to be able to specify the shared server process type.
When set to 1 - Shared, the server process used is retrieved from a pool. The socket connection between the application and server is made to a dispatcher process on the server. This setting allows there to be fewer processes than the number of connections, reducing the need for server resources. Use this value when a server must handle a large number of connections.
When set to 2 - Dedicated, a server process is created to service only that connection. When that connection ends, so does the process (UNIX and Linux) or thread (Windows). The socket connection is made directly between the application and the dedicated server process or thread. When connecting to UNIX and Linux servers, a dedicated server process can provide significant performance improvement, but uses more resources on the server. When connecting to Windows servers, the server resource penalty is insignificant. Use this value if you have a batch environment with a low number of connections.
This connection option can affect performance. See "Performance Considerations" for details.
The equivalent connection string attribute is ServerType.
Initialization String: Type a SQL string to manage session settings that will be issued immediately after connecting to the database.
For example, to change the language of the current session to American, type alter session set NLS_LANGUAGE = 'AMERICAN'.
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.
You can also use OS Authentication to connect to your Oracle database. See "OS Authentication" for details.
Authentication Method: Select the method the driver uses to authenticate the user to the server when a connection is established.
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 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.
When set to 4 - Kerberos, the driver uses Kerberos authentication. This method supports both Windows Active Directory Kerberos and MIT Kerberos environments.
When set to 5 - Kerberos with UID & PWD, the driver uses both Kerberos authentication and user ID and password authentication. The driver first authenticates the user using Kerberos. If a user ID and password are specified, the driver reauthenticates using the user name and password supplied. An error is generated if a user ID and password are not specified.
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.
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.
Keystore: Type the path that specifies the location of the keystore file. The keystore file contains a list of the valid client certificates that are trusted by the server for optional Client Authentication with SSL.
NOTE: The keystore and trust store files may be the same file.
Keystore Password: Type the password required to access the keystore.
NOTE: The keystore and trust store files may be the same file and, therefore, have the same password.
Key Password: Type the password required to access an individual key in the keystore.
The keys stored in a keystore can be individually password-protected. For these types of keystores, the driver needs the key password to be able to extract the key from the keystore. The value specified for Key Password must be the password of the specific key that the driver needs to use.
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 Host option value specified as part of a data source or connection string to the dnsName value or the commonName.
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.
Wire Protocol Mode: Select whether the driver optimizes network traffic to the Oracle server.
When set to 1 (the default), the driver operates in normal wire protocol mode without optimizing network traffic.
When set to 2, the driver optimizes network traffic to the Oracle server for result sets that contain repeating data in some or all of the columns, and the repeating data is in consecutive rows. It also optimizes network traffic if the application is updating or inserting images, pictures, or long text or binary data.
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 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 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.
This connection option can affect performance. See "Performance Considerations" for details.
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.
Cached Cursor Limit: Type a value from 0 to 65535. The default value is 32. This value corresponds to the number of Oracle Cursor Identifiers that the driver stores in cache. A Cursor Identifier is needed for each concurrent open Select statement. When a Select statement is closed, the driver stores the identifier in its cache, up to the limit specified, rather than closing the Cursor Identifier. When a new Cursor Identifier is needed, the driver takes one from its cache, if one is available. Cached Cursor Identifiers are closed when the connection is closed.
This connection option can affect performance. See "Performance Considerations" for details.
Cached Description Limit: Type a value from 0 to 65535. The default value is 0. This value corresponds to the number of descriptions that the driver saves for Select statements. These descriptions include the number of columns, data type, length, and scale for each column. When this option is enabled, applications that issue a Select statement that returns a few rows repeatedly can realize a significant performance benefit.
NOTE: If the Select statement contains a Union or a nested Select, the description is not cached.
This connection option can affect performance. See "Performance Considerations" for details.
The equivalent connection string is CachedDescLimit.
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 Wire Protocol driver, you must specify the host name, port number, and either the SID or service name of each alternate server. The string has the format:
(HostName=hostvalue:PortNumber=portvalue:{SID=sidvalue | ServiceName=servicevalue}[, . . .])
For example, the following Alternate Servers value defines two alternate database servers for connection failover:
(HostName=AccountingOracleServer:
PortNumber=1521:SID=Accounting,
HostName=255.201.11.24:PortNumber=1522:
ServiceName=ABackup.NA.MyCompany)
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.
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.