Connecting to a Data Source Using a Connection String

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 connection string has the form:

DSN=data_source_name[;attribute=value[;attribute=value]...] 

The FILEDSN connection string has the form:

FILEDSN=filename.dsn[;attribute=value[;attribute=value]...] 

The DSN-less connection string specifies a driver instead of a data source. All connection information must be entered in the connection string because there is no data source storing the information.

The DSN-less connection string has the form:

DRIVER=[{]driver_name[}][;attribute=value[;attribute=value]
...] 

Table 6-1 gives the long and short names for each attribute, as well as a description. You can specify either long or short names in the connection string. Connection string attribute names are the same as the option names on the driver Setup dialog box tabs unless otherwise noted. The connection string attribute name does not have spaces between the words. For example, the connection string attribute name ApplicationUsingThreads is equivalent to the option name Application Using Threads.

The defaults listed in the table are initial defaults that apply when no value is specified in either the data source definition or in the connection string. If you specified a value for the attribute when configuring the data source, that value is the default.

An example of a DSN connection string with overriding attribute values for Oracle Wire Protocol is:

DSN=Accounting;ID=JOHN;PWD=XYZZY 

A FILEDSN connection string is similar except for the initial keyword:

FILEDSN=OracleWP.dsn;ID=JOHN;PWD=XYZZY 

A DSN-less connection string must provide all necessary connection information:

DRIVER=DataDirect Oracle Wire Protocol; 
HOST=server1;PORT=1522;UID=JOHN;PWD=XYZZY; 
SERVICENAME=SALES.US.ACME.COM 
 



  
 

Table 6-1.  Oracle Wire Protocol Connection String Attributes 


  
    
 

Attribute


    
 

Description



  
    
 

AlternateServers	 (ASRV)


    
 

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 connection string attribute 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 AlternateServers value defines two alternate database servers for connection failover:

AlternateServers=(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 string attributes that you can set for this feature.



  
    
 

ApplicationUsing
Threads (AUT)


    
 

ApplicationUsingThreads={0 | 1}. Determines whether the driver works with multi-threaded applications. 

 

When set to 1 (the initial default), the driver is thread-safe and is ensured to work with multi-threaded applications. 

 

When using the driver with single-threaded applications, you can set this option to 0 to avoid additional processing required for ODBC thread-safety standards.   

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

ArraySize (AS)


    
 

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). 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 initial default is 60000.

 

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 attribute can affect performance. See "Performance Considerations" for details.



  
    
 

Authentication
Method (AM)


    
 

AuthenticationMethod={1 | 3 | 4 | 5}. Determines the security method the driver uses to authenticate the user to the server when a connection is established. 

 

When set to 1, the driver sends the user ID in clear text and an encrypted password to the server for authentication.

 

When set to 3, 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, the driver uses Kerberos authentication. This method supports both Windows Active Directory Kerberos and MIT Kerberos environments.

 

When set to 5, 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.

 

If the specified authentication method is not supported by the database server, the connection fails and the driver generates an error.

 

See "Using Security" for a general description of authentication and its configuration requirements.



  
    
 

CachedCursorLimit (CCL)


    
 

The number of Oracle Cursor Identifiers, from 0 to 65535, that the driver stores in cache. A Cursor Identifier is needed for each concurrent open Select statement. When a result set 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.

 

The initial default is 32.

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

CachedDescLimit (CDL)


    
 

The number of descriptions, from 0 to 65535, that the driver saves for Select statements. These descriptions include number of columns, data type, length, and scale for each column. The matching is done by an exact-text match through the From clause. The initial default is 0 because of the overhead of parsing the SQL statement. Using the From clause, applications that issue a Select statement that returns a few rows repeatedly can realize a significant performance benefit when using this attribute.

 

NOTE: If the Select statement contains a Union or a nested Select, the description is not cached.

 

This attribute can affect performance. See "Performance Considerations" for details.

 

The equivalent Setup dialog box option is Catalog Functions Include Synonyms.



  
    
 

CatalogIncludesSynonyms (CIS)


    
 

CatalogIncludesSynonyms={0 | 1}. Determines whether synonyms are included in calls to SQLProcedures, SQLStatistics, and SQLProcedureColumns.

 

When set to 1, synonyms are included in these calls.

 

When set to 0, synonyms are not included (a non-standard behavior) and performance is improved.

 

The initial default is 1.

 

This attribute can affect performance. See "Performance Considerations" for details.

 

The equivalent Setup dialog box option is Cached Description Limit.



  
    
 

CatalogOptions (CO)


    
 

CatalogOptions={0 | 1}. Determines whether the result column REMARKS (for the catalog functions SQLTables and SQLColumns) and the result column COLUMN_DEF (for the catalog function SQLColumns) return actual values.

 

When set to 1, REMARKS and COLUMN_DEF return actual values.

 

When set to 0 (the initial default), REMARKS and COLUMN_DEF return SQL_NULL_DATA.

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

ConnectionRetryCount (CRC)


    
 

Specifies 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 initial 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 attribute and the ConnectionRetryDelay connection string attribute, 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 string attributes that you can set for this feature.



  
    
 

ConnectionRetryDelay (CRD)


    
 

Specifies 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 initial default is 3 (seconds). When set to 0, there is no delay between retries.

 

NOTE: This attribute has no effect unless the ConnectionRetryCount connection string attribute is set to an integer value greater than 0.

 

This attribute and the ConnectionRetryCount connection string attribute, 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 string attributes that you can set for this feature.



  
    
 

DataSourceName (DSN)


    
 

A string that identifies an Oracle data source configuration. Examples include Accounting or Oracle-Serv1.



  
    
 

DefaultLongDataBuffLen (DLDBL)

 

 


    
 

An integer factor value that specifies, in 1024-byte multiples, the maximum length of data fetched from Long/LOB columns. The value must be in multiples of 1024 (for example, 1024, 2048). 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 attribute 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.

 

The initial default is 1024.

 

This attribute can affect performance. See "Performance Considerations" for details.

 

The equivalent Setup dialog box option is Default Buffer Size for Long/LOB Columns (in KB).



  
    
 

DescribeAtPrepare (DAP)


    
 

DescribeAtPrepare={0 | 1}. Determines whether the driver describes the SQL statement at prepare time.

 

When set to 0 (the initial default), the driver does not describe the SQL statement at prepare time.

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

EnableDescribeParam (EDP)


    
 

EnableDescribeParam={0 | 1}. Determines whether the ODBC API function SQLDescribeParam is enabled.

 

When set to 1, the SQLDescribeParam function describes all parameters 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 attribute must be set to 1 when using Microsoft Remote Data Objects (RDO) to access data. 

 

The initial default is 0.

 

The equivalent Setup dialog box option is Enable SQLDescribeParam.



  
    
 

EnableNcharSupport (ENS)


    
 

EnableNcharSupport={0 | 1}. Determines whether the N-types NCHAR, NVARCHAR2, and NCLOB are supported.

 

When set to 1, 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. See "Unicode Support" for details.

 

NOTE: Valid only on Oracle 9i and higher.

 

The initial default is 0.



  
    
 

EnableScrollableCursors (ESC)


    
 

EnableScrollableCursors={0 | 1}. Determines whether scrollable cursors are enabled for the data source.

 

When set to 1 (the initial default), both Keyset and Static cursors are enabled.

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

EnableStaticCursorsFor
LongData (ESCLD)


    
 

EnableStaticCursorsForLongData={0 | 1}. Determines whether the driver supports Long columns when using a static cursor. Using this attribute causes a performance penalty at the time of execution when reading Long data. 

 

The initial default is 0.

 

NOTE: You must set this attribute to 1 if you want to persist a result set that contains Long data into an XML data file.

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

EnableTimestampWith
Timezone (ETWT)


    
 

EnableTimestampWithTimezone={0 | 1}. Determines whether the driver exposes timestamps with timezones to the application.

 

When set to 1, 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'.

 

The initial default is 0.



  
    
 

Encryption
Method (EM)


    
 

EncryptionMethod={0 | 1}. Specifies the method the driver uses to encrypt data sent between the driver and the database server. 

 

When set to 0 (the default), data is not encrypted.

 

When set to 1, 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.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

 This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

GSSClient (GS)


    
 

Specifies the GSS client library that the driver uses to communicate with the Key Distribution Center (KDC). The initial default 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.

 

See "Using Security" for a general description of authentication and its configuration requirements.

 

 



  
    
 

HostName (HOST)


    
 

HostName={servername | IP_address}. Identifies the Oracle server to which you want to connect. If your network supports named servers, you can specify a server name such as Oracleserver. Otherwise, specify an IP address such as 199.226.224.34.

 

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.

 

Do not use this attribute if you have specified the ServerName (SRVR) attribute.

 

The equivalent Setup dialog box option is Host.



  
    
 

HostNameInCertificate (HNIC)


    
 

Specifies whether the driver validates the host name contained in the certificate returned by the database server on systems using SSL. The host name is established by the SSL administrator. If no value is specified for HostNameInCertificate, the driver does not check the host name in the server certificate. The value of HostNameInCertificate is ignored if ValidateServerCertificate is set to 0 or if EncryptionMethod does not specify SSL.

 

If a value is specified for HostNameInCertificate, 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 HostNameInCertificate with the dnsName value. The connection succeeds if the values match. The connection fails if the HostNameInCertificate 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 HostNameInCertificate 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 HostNameInCertificate value does not match the commonName. If multiple commonName parts exist in the Subject name of the certificate, the connection succeeds if the HostNameInCertificate value matches any of the Common Name parts.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

If the value specified for HostNameInCertificate is the special value #SERVERNAME#, then the driver compares the HostName (HOST) attribute value specified as part of a data source or connection string to the dnsName value or the commonName.



  
    
 

IANAAppCodePage (IACP)

 




    
 

For a list of valid values for this attribute, 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 attribute 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:


 
In the connection string
 
In the Data Source section of the system information file (odbc.ini)
 
In the ODBC section of the system information file (odbc.ini)

 

If no IANAAppCodePage value is found, the driver uses the default value of 4 (ISO 8859-1 Latin-1).



  
    
 

KeyPassword (KP)


    
 

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 requires 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.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

 



  
    
 

KeyStore (KS)


    
 

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 truststore files may be the same file.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

 



  
    
 

KeyStorePassword (KSP)


    
 

The password required to access the keystore.

 

NOTE: The keystore and truststore files may be the same file and, therefore, have the same password.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

 



  
    
 

LoadBalancing (LB)


    
 

LoadBalancing={0 | 1}. Determines whether the driver uses client load balancing in its attempts to connect to primary and alternate database servers. See "Using Client Load Balancing" for more information.

 

When set to 1, the driver attempts to connect to the database servers in random order. 

 

When set to 0 (the initial 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 attribute has no effect unless alternate servers are defined for the AlternateServers connection string attribute.

 

The LoadBalancing connection string attribute 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 string attributes that you can set for this feature.



  
    
 

LocalTimeZoneOffset (LTZO)


    
 

Determines whether the driver acquires local time zone information from the operating system. The initial default value is "" (empty string), which means that, on Windows, the driver checks the operating system. If the information 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 in the following format: (-)HH:MM. For example, -08:00 equals GMT minus 8 hours. The driver uses the value of the attribute to issue an "ALTER SESSION" for the local time zone at connect time.



  
    
 

LockTimeOut (LTO)


    
 

LockTimeOut={0 | -1}. Determines whether Oracle waits for a lock to be freed before raising an error when processing a Select...For Update statement. When connected to an Oracle 9i or higher server, you can specify the number of seconds to wait by setting this attribute to an integer greater than 0.

 

When set to 0, Oracle does not wait.

 

When set to -1 (the initial default), Oracle waits indefinitely.

 

If you are connected to an Oracle 8i server, any value greater than 0 is equivalent to the value -1.

 

This attribute can affect performance. See "Performance Considerations" for details.



  
    
 

LogonID (UID)


    
 

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 Setup dialog box option is User Name.

 

You can also use OS Authentication to connect to your Oracle database. See "OS Authentication" for details.



  
    
 

Password (PWD)


    
 

The password that the application uses to connect to your Oracle database.

 

You can also use OS Authentication to connect to your Oracle database. See "OS Authentication" for details.



  
    
 

PortNumber (PORT)


    
 

Identifies the port number of your Oracle listener. Check with your database administrator for the correct number.

 

Do not use this attribute if you have specified the ServerName (SRVR) attribute.



  
    
 

ProcedureRetResults (PRR)



    
 

ProcedureRetResults={0 | 1}. Determines whether the driver returns result sets from stored procedure functions. 

 

When set to 0 (the initial default), the driver does not return result sets from stored procedures.

 

When set to 1, the driver returns result sets from stored procedures. See "Stored Procedure Results" for details. When set to 1 and you execute a stored procedure that does not return result sets, you will incur a small performance penalty.

 

This attribute can affect performance. See "Performance Considerations" for details.

 

The equivalent Setup dialog box option is Procedure Returns Results.



  
    
 

ReportCodePage
ConversionErrors (RCCE)


    
 

ReportCodePageConversionErrors={0 | 1 | 2}. Provides flexibility for the way in which the driver returns error or warning messages associated with code page conversion. 

 

When set to 0 (the initial 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.

 

Settings 1 and 2 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, if the driver encounters code page conversion errors, it returns an error instead of substituting 0x1A for unconverted characters.

 

When set to 2, if the driver encounters code page conversion errors, it substitutes 0x1A for each character that cannot be converted and returns a warning.



  
    
 

ReportRecycleBin (RRB)


    
 

ReportRecycleBin={0 | 1}. Determines whether the driver reports objects that are in the Oracle Recycle Bin.

 

When set to 0 (the initial default), the driver does not report tables that are in the recycle bin.

 

When set to 1, the driver reports tables that are in the recycle bin.

 

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 Setup dialog box option is Report Objects in Recycle Bin.



  
    
 

ServiceName (SN)


    
 

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 comprises 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 ServiceName connection string attribute.

 

If you set a value for this attribute, do not use the SID (SID), or the ServerName (SRVR) and TNSNamesFile (TNF) attributes, and vice versa.



  
    
 

ServerName (SRVR)


    
 

Specifies a net service name that exists in the TNSNAMES.ORA file. The corresponding entry in the TNSNAMES.ORA file is used to obtain HostName, PortNumber, and ServiceName or SID information.

 

If you set a value for this attribute, do not use the SID (SID), ServiceName (SN), HostName (HOST), and PortNumber (PORT) attributes, and vice versa.



  
    
 

ServerType (ST)


    
 

ServerType={0 | 1 | 2}. Specifies whether the connection is established using a shared or dedicated server process (dedicated thread on Windows).

 

If set to 0 (the initial default), the driver uses the default server type 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 attribute can affect performance. See "Performance Considerations" for details.

 

The equivalent Setup dialog box option is Server Process Type.



  
    
 

 SID (SID)


    
 

The Oracle System Identifier that refers to the instance of the Oracle database software running on the server.

 

If you set a value for this attribute, do not use the ServiceName (SN), or the ServerName (SRVR) and TNSNamesFile (TNF) attributes, and vice versa.



  
    
 

TimestampEscapeMapping (TEM)


    
 

TimestampEscapeMapping={0 | 1}. Determines how the driver maps Date, Time, and Timestamp literals.

 

When set to 0 (the initial 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, the driver always uses the Oracle 8.x TO_DATE function as if connected to an Oracle 8.x server.

 

When this attribute is set to 0, 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.



  
    
 

TNSNamesFile (TNF)


    
 

Specifies 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 the HostName, PortNumber, and SID.

 

This attribute is ignored if no ServerName (SRVR) value is specified. If this attribute is left as an empty string, 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 set a value for this attribute, do not use the SID (SID), ServiceName (SN), HostName (HOST), and PortNumber (PORT) attributes, and vice versa.

 

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:

 

TNSNamesFile=(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.

 

ConnectionRetryCount (CRC) and ConnectionRetryDelay (CRD) are also valid with TNSNames failover. The driver will make at least one attempt to open the files, and, if ConnectionRetryCount is enabled, more than one. If ConnectionRetryDelay is enabled, the driver waits the specified number of seconds between attempts. LoadBalancing (LB) is not available for TNSNames failover.



  
    
 

TrustStore (TS)


    
 

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.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

 



  
    
 

TrustStorePassword (TSP)


    
 

The password required to access the truststore.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

 



  
    
 

UseCurrentSchema (UCS)


    
 

UseCurrentSchema={0 | 1}. Specifies whether the driver returns only procedures owned by the current user when executing SQLProcedures.

 

When set to 1 (the initial default), the call for SQLProcedures is optimized, but only procedures owned by the user are returned.

 

When set to 0, the driver does not specify only the current user.

 

This attribute can affect performance. See "Performance Considerations" for details.

 

The equivalent Setup dialog box option is Use Current Schema for SQLProcedures.



  
    
 

ValidateServerCertificate (VSC)


    
 

ValidateServerCertificate={0 | 1}. Determines whether the driver validates the security certificate of the server as part of the SSL authentication handshake.

 

When set to 0, the driver does not validate the certificate.

 

	When set to 1 (the initial default), the driver validates the certificate.

 

See "Using Security" for a general description of encryption and its configuration requirements.

 

 



  
    
 

WireProtocolMode (WPM)


    
 

WireProtocolMode={1 | 2}. Specifies whether the driver optimizes network traffic to the Oracle server.

 

When set to 1 (the initial 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 attribute can affect performance. See "Performance Considerations" for details.