Oracle Data Provider Connection String Options

OracleConnectionStringBuilder property names are the same as the connection string option names of the OracleConnection object. However, the connection string option name has spaces between the words. For example, the connection string option name Alternate Servers is equivalent to the property name AlternateServers.

The following connection option descriptions are listed alphabetically by the connection string option name. The ConnectionStringBuilder property name is listed immediately underneath the GUI name.

Accounting Info

Property

AccountingInfo

Description

Specifies the name of an accounting string. This sets the CLIENT_INFO column value in the V$SESSION table on the Oracle server using the DBMS_APPLICATION_INFO.SET_CLIENT_INFO procedure.

Valid Values

String

Default

An empty string

Category

Client Monitoring

Alternate Servers

Property

AlternateServers

Description

Specifies a list of alternate database servers to which the data provider tries to connect if the primary database server is unavailable. Specifying a value for this connection string option enables connection failover for the data provider.

The value you specify must be in the form of a string that defines connection information for each alternate server. For the Oracle data provider, you must specify the name or the IP address of each alternate server and the port number of each alternate server.

The Server Type and SID or Service Name connection string options are optional for each alternate server.

See Configuring Connection Failover for a discussion of connection failover and information about other connection string options that you can set for this feature.

Valid Values

"Host=hostvalue;Port=portvalue[, ...]"

Example

The following Alternate Servers value defines two alternate servers for connection failover:

Alternate Servers="Host=AcctOracleServer;Port=1521;Service Name=ORCL, Host=255.210.11.25;Port=1521;Service Name=ORCL"

Default

An empty string

Category

Failover

Application Name

Property

ApplicationName

Description

Specifies the name of the application currently using the connection. This sets the PROGRAM column value in the V$SESSION table on the Oracle server.

Valid Values

string

where string is the name of the application.

Default

An empty string

Category

Client Monitoring

Array Send Size

Property

ArraySendSize

Description

Specifies the size of arrays used when performing array binding, in particular during bulk load operations. The value is specified in kilobytes.

See Performance Considerations for information about configuring this option for optimal performance.

Valid Values

The value for this option can be an integer from 1 to 4,294,967,296 (4 GB). The value 1 is a special value that does not define the number of bytes but, instead, causes the data provider to allocate space for exactly one row of data.

Default

4096

Category

Performance

Authentication Method

Property

AuthenticationMethod

Description

Determines which authentication method the data provider uses when establishing a connection.

Valid Values

Client | Kerberos | KerberosUserIDPassword | UserIDPassword

If set to Client, the data provider uses client authentication. Client authentication uses the user ID of the user logged onto the system on which the data provider is running to authenticate the user to the database. Because the database server does not authenticate the user, use client authentication only when you can guarantee that only trusted clients can access the database server.

If set to Kerberos, the data provider uses Kerberos authentication. The data provider ignores any user ID or password specified.

If set to KerberosUserIDPassword, the data provider first uses Kerberos when establishing a connection. Next, the data provider reauthenticates the user through user ID/password authentication, using the User ID and Password connection string options. If the user ID and password are not specified, the data provider throws an exception. If either Kerberos or user ID/password authentication fails, the connection attempt fails and the data provider throws an exception.

If set to UserIDPassword or if no value is set, the data provider uses the Oracle user ID/password authentication. If a user ID and password are not specified, the data provider throws an exception.

Default

UserIDPassword

Category

Security

Batch Update Behavior

Property

BatchUpdateBehavior

Description

Determines how the data provider optimizes batch processing during update operations. The BatchUpdateSize property must be set to an integer greater than 1 (see OracleDataAdapter Class for more information).

Valid Values

ArrayBindWhenPossible | ArrayBindOnlyInserts | NoOptimizations

If set to ArrayBindWhenPossible, the data provider attempts to use array binding to optimize batch updates. Use this value if your application 1) uses batch operations for inserts, updates, or deletes and 2) performs these operations on many values in the same columns. In this case, set the Batch Update Behavior connection string option.

If set to ArrayBindOnlyInserts, the data provider can use array binding to optimize batch inserts. Use this value if your application 1) uses batch operations for inserts only and 2) inserts many values in the same columns.

If set to NoOptimizations, no optimizations are used during DataAdapter update operations.

Default

ArrayBindWhenPossible

Category

Performance

Bulk Load Protocol

Property

Option Name

Description

Specifies the protocol that the data provider performs bulk loads.

Valid Values

Standard | Bulk | Auto

If set to Standard, the data provider uses array binding.

If set to Bulk, the data provider uses the bulk protocol for all bulk load operations. If the bulk protocols cannot be used, the load operation fails with an exception. Using a different value for this option may alleviate the problem.

If set to Auto, the data provider attempts to use the database's bulk protocol for all bulk operations. If the bulk protocols cannot be used, the data provider uses the best parameter protocol possible for the database.

Default

Auto

Category

Bulk Load

Certificate Store Location

Property

CertificateStoreLocation

Description

Specifies the location of the X.509 certificate store used for client authentication.

Valid Values

Current User | Local Machine | Wallet Path

Default

Current User

Category

Security

Certificate Store Password

Property

CertificateStorePassword

Description

Specifies the password of the certificate store used for server authentication.

Valid Values

Password String

Default

Empty String

Category

Security

Client Host Name

Property

ClientHostName

Description

Specifies the name that the Oracle server uses to identify the client workstation name by setting the MACHINE and TERMINAL column values in the V$SESSION table.

Valid Values

string

where string is the host name of the client machine.

Default

An empty string

Category

Client Monitoring

Client User

Property

ClientUser

Description

Specifies the OSUSER column in the V$SESSION table.

Valid Values

NULL | string

where string is a valid user ID.

Default

An empty string

Category

Client Monitoring

Code Page Override

Property

CodePageOverride

Description

Specifies the code page to be used by the data provider to convert character data. Use this property only if you need to change the data provider’s default behavior. ]

Valid Values

None | UTF8

When set to None, the data provider determines which code page to use to convert character data.

When set to UTF8, the data provider uses UTF-8 to convert character data.

Default

None

Category

Advanced

Commit Behavior

Property

CommitBehavior

Description

Supported in Oracle 10g R2 and higher

Typically, redo changes generated by update transactions are written to disk immediately when an transaction is committed, and the session waits for the disk write to complete before returning control to the application. On Oracle 10g R2 and higher, the log writer can write the redo changes to disk in its own time instead of immediately and return control to the application before the disk write is complete instead of waiting. This property controls this behavior by setting the value of the Oracle COMMIT_WRITE session parameter.

Not waiting for redo log changes to be written to disk improves performance for applications that have both of the following characteristics:

• Applications that perform update operations.
• Applications where data integrity is not critical. For example, most banking applications cannot tolerate data loss in the event that the server has a problem writing the redo log changes to disk or fails during the process, but many logging applications for diagnostic purposes can.

See Performance Considerations for information about configuring this option for optimal performance.

Valid Values

ServerDefault | WaitImmediate | WaitBatch | NoWaitImmediate | NoWaitBatch

If set to ServerDefault, the data provider uses the redo log behavior set by the database server.

If set to WaitImmediate, the commit operation does not return control to the application until the redo changes are written to disk. Redo information is written to disk immediately. Use this value if your application processes multiple update transactions one at a time.

If set to WaitBatch, the commit operation does not return control to the application until redo changes are written to disk. The write task may be deferred by the server until additional transactions are ready to be written to disk. Use this value if your application processes multiple update transactions simultaneously. Using this value when an application performs only a few transactions decreases performance.

If set to NoWaitImmediate, redo changes are written to disk immediately, but the commit operation returns control to the application without waiting for this operation to complete. Use this value if your application processes multiple update transactions one at time and data integrity is not critical.

If set to NoWaitBatch, the redo write task may be deferred by the server until additional transactions are ready to be written to disk, but the commit operation returns control to the application without waiting for this operation to complete. Use this value if your application processes multiple update transactions simultaneously and data integrity is not critical.

Default

ServerDefault

Category

Advanced

Common Work Arounds

Property

WorkArounds

Description

This option is reserved. Enter values only when directed by Progress customer support.

Default

0

Category

Advanced

Connection Pool Behavior

Property

ConnectionPoolBehavior

Description

Specifies the order in which a connection is removed from the connection pool for reuse, based on how frequently or how recently the connection has been used.

Note: This option is ignored if Reauthentication Enabled is set to True.

Valid Values

LeastRecentlyUsed | MostRecentlyUsed | LeastFrequentlyUsed | MostFrequentlyUsed

If set to MostRecentlyUsed, the data provider uses a Last In First Out (LIFO) approach to return the connection that was returned to the pool most recently.

If set to LeastRecentlyUsed, the data provider uses a First In First Out (FIFO) approach to return the connection that has been in the pool for the longest time. This value ensures a balanced use of connections in the pool.

If set to MostFrequentlyUsed, the data provider returns the connection with the highest use count. This value enables applications to give preference to the most seasoned connection.

If set to LeastFrequentlyUsed, the data provider returns the connection with the lowest use count. This value ensures a balanced use of connections in the pool.

Default

LeastRecentlyUsed

Category

Connection Pooling

Connection Reset

Property

ConnectionReset

Description

Specifies whether a connection that is removed from the connection pool for reuse by an application will have its state reset to the initial configuration settings of the connection.

Valid Values

True | False

If set to True, the state of connections removed from the connection pool for reuse by an application is reset to the initial configuration of the connection. Resetting the state impacts performance because the new connection must issue additional commands to the server, for example, resetting the current database to the value specified at connect time.

If set to False, the state of connections is not reset.

Default

False

Category

Connection Pooling

Connection Retry Count

Property

ConnectionRetryCount

Description

Specifies the number of times the data provider tries to connect to the primary server, and, if specified, the alternate servers after the initial unsuccessful attempt.

Valid Values

0 | x

where x is a positive integer from 1 to 65535.

If set to 0, the data provider does not try to reconnect after the initial unsuccessful attempt.

If set to x, the data provider attempts to connect the specified number of times. If a connection is not established during the retry attempts, the data provider returns an error that is generated by the last server to which it attempted to connect.

Default

0

Category

Failover

Connection Retry Delay

Property

ConnectionRetryDelay

Description

Specifies the number of seconds the data provider waits after the initial unsuccessful connection attempt before retrying a connection to the primary server, and, if specified, the alternate servers.

Note: This option has no effect unless the Connection Retry Count connection string option is set to an integer value greater than 0.

Valid Values

0 | x

where x is a positive integer from 1 to 65535.

If set to 0, there is no delay between retrying the connection.

If set to x, the data provider waits the specified number of seconds between connection retry attempts.

Default

3

Category

Failover

Connection Timeout

Property

ConnectionTimeout

Description

Specifies the number of seconds after which the attempted connection to the database server fails if not yet connected. If connection failover is enabled, this option applies to each connection attempt. A value of 0 means that the data provider never times out on a connection attempt.

Note: This property is not supported with the Oracle Entity Framework data provider. Instead, the data provider uses the ADO.NET Entity Framework programming contexts.

Valid Values

0 | x

where x is a positive integer greater than 1.

Default

15

Category

Connection Pooling

Credentials Cache

Property

CredentialsCache

Description

Specifies the credentials cache that the Kerberos.NET library uses to communicate with the Key Distribution Center (KDC) during authentication in a Kerberos environment.

Valid Values

An empty string | path_to_Credentials_Cache_File | MSLSA:

If set to an empty string, the data provider checks the KRB5CCNAME environment variable. If the KRB5CCNAME environment variable is set, its value is used as the credentials cache path.

If set to path_to_Credentials_Cache_File, the data provider uses the specified file-based cache. When specifying a file path, the value must be a fully qualified local file system path. UNC paths, network paths, and paths containing upward traversal components (..) are not supported.

If set to MSLSA:, the data provider uses the Windows Local Security Authority (LSA) cache (Windows only) for user credentials.

Notes

• This option is ignored unless the Authentication Method connection string option is set to Kerberos.
• If neither the option nor the environment variable is set, the data provider uses the value MSLSA: to access the Microsoft Local Security Authority (LSA) cache.

Default

MSLSA:

Category

Security

Cursor Description Cache

Property

CursorDescriptionCache

Description

Specifies whether to explicitly force the binding or rebinding of the packages needed by the data provider.

A rebind can be needed to change a bind-option used for the provider packages, for example, to change the Default Qualifier. When the packages are not found on the database, the data provider automatically attempts to bind them.

Note: The Oracle Entity Framework data provider does not support this option in a connection string. Instead, the data provider uses the ADO.NET Entity Framework programming contexts to determine whether to reuse cached result set description information when the data provider is requested to execute a SELECT statement that exactly matches a previously executed SELECT statement.

Valid Values

True | False

If set to False, the data provider does not attempt to bind packages unless they are missing.

If set to True, the data provider attempts to bind packages unless they are missing.

Default

True

Category

Performance

Data Integrity Level

Property

DataIntegrityLevel

Description

Determines the level of Oracle Advanced Security data integrity used for data sent between the data provider and database server. The connection fails if the database server does not have a compatible integrity algorithm.

Valid Values

rejected | accepted | requested | required

If set to rejected, the data provider does not enable a data integrity check for data sent between the data provider and database server. The connection fails if the database server specifies REQUIRED.

If set to accepted, the data provider enables a data integrity check for data sent between the data provider and database server if the database server requests or requires it.

If set to requested, the data provider enables a data integrity check for data sent between the data provider and database server if the database server permits it.

If set to required, the data provider performs a data integrity check for data sent between the data provider and database server. The database server must have data integrity check enabled. The connection fails if the database server specifies REJECTED.

Notes:

• When this property is set to accepted, requested, or required, the DataIntegrityTypes connection property determines the algorithm the data provider uses to protect against attacks that intercept and modify the data being transmitted between the client and server.
• You can enable data integrity protection without enabling encryption.
• Consult the Oracle administrator to verify the data integrity settings of your Oracle server.

Default

Accepted

Category

String

Data Integrity Types

Property

DataIntegrityTypes

Description

Determines the algorithm the data provider uses to protect against attacks that intercept and modify data being transmitted between the client and server when data integrity is enabled using the DataIntegrityLevel property.

Valid Values

MD5 | SHA1 | SHA256 | SHA384 | SHA512 | ALL | NONE

Oracle Advanced Security Algorithms for Data Integrity

Notes:

• The value of this property is ignored if the DataIntegrityLevel property is set to rejected.
• Consult the Oracle administrator to verify the data encryption settings of your Oracle server.

Default

All

Data Type

String

Data Source

Property

DataSource

Description

Specifies either the net service name (when used with the TNSNames File option) or a connection string value based on the format used in the tnsnames.ora file.

If the net service name is specified as a value for the Data Source connection string option, but no value is specified for the TNSNames File connection string option, the path to the tnsnames.ora file is taken from the Oracle section of the Registry.

Note: If using a tnsnames.ora file to provide connection information, or using the SID or Data Source connection string options, do not specify Service Name.

Alias

Server Name

Valid Values

string

where string is either the net service name or the connection string.

Example

If the value is a net service name:

Data Source=oracleservice

If the value is a connection string:

Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(Host=server3)(PORT=1521))(CONNECT_DATA=(SID=ORCL)));

Default

An empty string

Category

TNSNames Connection

Enable Manual Enlistment

Property

EnableManualEnlistment

Description

Specifies whether the data provider permits manual enlistment in distributed transactions after the connection is opened.

See Performance Considerations for information about enlisting in distributed transactions can affect performance.

Valid Values

True | False

If set to True, the connection, once opened, can be manually enlisted in distributed transactions.

If set to False, the connection, once opened, cannot be manually enlisted in distributed transactions.

Default

False

Category

Advanced

Enable Server Result Cache

Property

EnableServerResultCache

Description

Determines whether the data provider adds a hint to SQL statements to enable Oracle’s server-side resultset caching feature, which stores the result set in database memory so that it can be reused. Server-side resultset caching can improve performance if your application executes the same query multiple times. This option only applies to connections to Oracle 11g database servers that support server-side resultset caching.

See Performance Considerations for information about configuring this option for optimal performance.

Valid Values

True | False

If set to True, the data provider adds a hint to SQL statements to enable server-side resultset caching.

If set to False, the data provider does not add a hint to the SQL statement.

Example

If enabled, the data provider adds a hint to SQL statements. For example:

SELECT /*+ result_cache */ * FROM employees 

Default

False

Category

Performance

Enable Trace

Property

EnableTrace

Description

Specifies whether tracing is enabled.

Valid Values

0 | x

where x is a positive integer 1 or higher.

If set to x, tracing is enabled.

If set to 0, tracing is not enabled.

Default

0

Category

Tracing

Enable XA

Property

EnableXA

Description

Enables a workaround that provides limited support for tools such as Visual Studio LightSwitch that assume that the underlying data provider can promote a local transaction to a fully-distributed transaction on an as-needed basis. Currently, the data provider cannot promote a local transaction to a fully-distributed transaction.

Valid Values

True | False

When set to True and Enlist is set to True, distributed transactions are supported and calls to Connection.EnlistTransaction function normally. See Performance Considerations for information about using distributed transactions.

When set to False, the connection cannot be enlisted in a distributed transaction. Calls to Connection.EnlistTransaction start a local transaction.

Note: When set to False and Enlist is set to True, the data provider returns an error.

Default

True

Category

Advanced

Encryption Level

Property

EncryptionLevel

Description

Determines whether data is encrypted or decrypted when transmitted over the network between the data provider and database server using Oracle Advanced Security encryption.

Valid Values

rejected | accepted | requested | required

If set to rejected, data sent between the data provider and the database server is not encrypted or decrypted. The connection fails if the database server specifies REQUIRED.

If set to accepted, data sent between the data provider and the database server is encrypted or decrypted if the database server requests or requires it.

If set to requested, data sent between the data provider and the database server is encrypted or decrypted if the database server permits it.

If set to required, data sent between the data provider and the database server must be encrypted or decrypted. The connection fails if the database server specifies REJECTED.

Notes:

• When this property is set to accepted, requested, or required, the EncryptionTypes connection property determines the Oracle Advanced Security algorithms being used.
• To enable SSL encryption, you must set the EncryptionMethod connection property.
• Consult your database administrator to verify the data encryption settings of your Oracle server.

Default

Accepted

Data Type

String

Encryption Method

Property

EncryptionMethod

Description

Defines how the data provider encrypts data sent between the data provider and the data source. The data provider supports client authentication for SSL. Client authentication uses the user ID of the user logged onto the system on which the data provider is running to authenticate the user to the database.

Valid Values

NoEncryption | SSL

If set to NoEncryption, data sent between the data provider and the Oracle server is not encrypted.

If set to SSL, all data sent between the data provider and the server is encrypted with SSL. The data provider checks the value of the Validate Server Certification connection string option to perform the necessary server authentication if required.

When SSL is enabled, the following connection string options also apply:

• Host Name In Certificate

Notes:

• An exception is thrown if the data provider attempts to connect with an invalid encryption method, for example, using SSL when connecting with a server that does not support SSL.
• Because the database server does not authenticate the user when client authentication is used, use this method of authentication if you can guarantee that only trusted clients can access the database server.

Default

NoEncryption

Category

Security

Encryption Types

Property

EncryptionTypes

Description

Specifies one or multiple algorithms to use if Oracle Advanced Security encryption is enabled using the EncryptionLevel connection property.

Valid Values

value [[, value ]...]

where value is one of the following values specifying an algorithm from the following table:

Oracle Advanced Security Encryption Algorithms

Notes:

• Multiple values must be separated by commas. In addition, if this property is specified in a connection URL, the entire value must be enclosed in parentheses when multiple values are specified.
• If multiple values are specified and Oracle Advanced Security encryption is enabled using the EncryptionLevel property, the database server determines the algorithm to be used, based on how it is configured.
• If unspecified, a list of all possible values is sent to the database server. The database server determines the algorithm to be used, based on how it is configured.
• Consult the Oracle administrator to verify the data encryption settings of your Oracle server.
• The value of this property is ignored if the EncryptionLevel property is set to rejected.

Default

All

Data Type

String

Enlist

Property

Enlist

Description

Specifies whether the data provider automatically attempts to enlist the connection in creating the thread’s current transaction context.

Valid Values

True | False

If set to True, the data provider automatically attempts to enlist the connection.

If set to False, the data provider does not automatically attempt to enlist the connection.

See Performance Considerations for information about configuring this option for optimal performance.

Default

False

Category

Performance

Fetch Array Size

Property

FetchArraySize

Description

Specifies the number of bytes of data the connection uses to fetch multiple rows.

This connection string option can affect performance for the ADO.NET data provider. See Performance Considerations for more information.

Note: This property is useful for standard ADO.NET applications. However, it is not accessible from the ADO.NET Entity Framework. Instead, the data provider uses the Entity Framework programming contexts.

Valid Values

An integer from 1 to 2147483648

To improve performance with a large number of records, increase the value of this property. Larger values increase throughput by reducing the number of times the connection fetches data across the network.

Default

64000

Category

Performance

Floating Point Parameter Behavior

Property

FloatingPointParameterBehavior

Description

Determines which native data type the data provider uses when sending floating point parameter values to the server.

Note: For servers using Oracle versions prior to Oracle 10g, this option is ignored. Floating point parameters are always sent as NUMBER

Valid Values

Default | BinaryFloatingPoint | Number

When set to Default, the data provider uses BinaryFloatingPoint value semantics.

When set to BinaryFloatingPoint, the data provider sends floating point parameter values as BINARY_DOUBLE or BINARY_FLOAT.

When set to Number, the data provider sends floating point parameter values as NUMBER.

Default

Default

Category

Advanced

GSS Client

Property

GSSClient

Description

Specifies the full path of the third party GSS client library that the data provider uses to communicate with the Key Distribution Center (KDC) during authentication in an MIT Kerberos environment.

Notes:

• This option is ignored unless the Authentication Method connection string option is set to Kerberos.
• When Oracle Advanced Security (OAS) options are enabled in the Oracle database, the driver is required to read the session key in addition to the Kerberos ticket. In this scenario, MIT Kerberos version 4.1 or higher must be used.
• The specified path must be a fully qualified local file system path. UNC paths, network paths, and paths containing upward traversal components (..) are not supported.

Valid Values

An empty string | path_to_GSS_client_library

If set as an empty string, the data provider uses the GSS client that ships with the operating system. The data provider uses the standard shared library path for loading the specified client library.

Example

The GSS client library that you can download from the MIT Web site.

Default

An empty string

Category

Security

Host

Property

Host

Description

Specifies either the name or the IP address of the server to which you want to connect.

Note: Do not combine the Host and Service Name connection string options in a connection string when using the TNSNames File option. Supplying multiple terms for the Oracle server causes the data provider to throw an exception.

Valid Values

string

where string is a valid host name or IP address.

Example

If your network supports named servers, you can specify a server name such as OracleAppServer. Otherwise, specify an IP address such as 122.23.15.12. See Using IP Addresses for information about using IP addresses.

Default

An empty string

Category

Standard Connection

Host Name In Certificate

Property

HostNameInCertificate

Description

Specifies a host name for certificate validation when SSL encryption is enabled (Encryption Method=SSL) and validation is enabled (Validate Server Certificate=True). This connection string option provides additional security against man-in-the-middle (MITM) attacks by ensuring that the server that the data provider is connecting to is the server that was requested.

Valid Values

Empty string | host_name

If no host name is specified, the data provider compares the value specified for the Host option to the Common Name (CN) parts of the certificate’s Subject name. If the values do not match, the connection fails and the data provider throws an exception.

Note: If multiple CN parts are present, the data provider validates the host name against each CN part. If any one validation succeeds, a connection is established.

If SSL or validation is not enabled, this option is ignored.

Default

An empty string

Category

Security

Initial Command Timeout

Property

InitialCommandTimeout

Description

Specifies the default wait time (timeout in seconds) before the data provider terminates the attempt to execute the command and generates an error. This option provides the same functionality as the OracleCommand object’s CommandTimeout property without the need to make changes to the application code. Subsequently, an application can use the CommandTimeout property to override the Initial Command Timeout connection string option.

Valid Values

0 or x

where x is any positive integer

If set to 0, the query never times out.

Notes:

• Set the Initial Command Timeout option to a value that is greater than the largest default deadlock detection and timeout value on the server. This ensures that the application receives a more meaningful reply in case of a timeout.
• This property is useful for standard ADO.NET applications. However, it is ignored for ADO.NET Entity Framework applications. Instead, the Entity Framework data provider uses the Entity Framework programming contexts to determine the default wait time.

Example

For example, in the following C# code fragment, the connection string instructs the application to wait 60 seconds before terminating the attempt to execute the command. The application then specifies a CommandTimeout of 45 seconds, which overrides the value set in the connection string:

OracleCommand command = new OracleCommand();
OracleConnection conn = new OracleConnection("…; Initial Command Timeout=60; …");
conn .Open();
command.Connection = connection;
// command.CommandTimeout returns 60;
command.CommandTimeout = 45;
// command.CommandTimeout returns 45
command = new OracleCommand();
command.CommandTimeout = 45;
command.Connection = conn;
// command.CommandTimeout still returns 45

Default

30

Category

Advanced

Initialization String

Property

InitializationString

Description

Specifies one statement that is issued immediately after connecting to the database to manage session settings.

Note: If the statement fails to execute for any reason, the connection to the Oracle server fails. The data provider throws an exception that contains the error returned from the Oracle server.

Valid Values

command

where command is an Oracle statement.

Example

To set the date format on every connection using an Alter Session statement:

Initialization String=ALTER SESSION SET DATEFORMAT xxx 

Default

An empty string

Category

Connection Pooling

Kerberos Config Path

Property

KerberosConfigPath

Description

Specifies the absolute path to the Kerberos configuration file that the Kerberos.NET library uses to communicate with the Key Distribution Center (KDC) during authentication in a Kerberos environment.

Valid Values

An empty string | path_to_Kerberos_configuration_file

If set to an empty string, the data provider checks the KRB5_CONFIG environment variable.

If set to path_to_Kerberos_configuration_file, the variable value is used as the configuration file path. The specified path must be a fully qualified local file system path. UNC paths, network paths, and paths containing upward traversal components (..) are not supported.

Example

C:\KerberosConfig\krb5.ini

Notes:

• This option is ignored unless the Authentication Method connection string option is set to Kerberos and Use Kerberos DotNet is set to True.
• This option is mandatory when the Authentication Method connection string option is set to Kerberos and Use Kerberos DotNet is set to True.

Default

An empty string.

Category

Security

License Path

Property

LicensePath

Description

Specifies the fully qualified path to the DDTek.lic license file. The license file is installed by default in the product installation directory.

Valid Values

A fully-qualified path

If set to an empty string the data provider looks for the license file in the application’s current directory. If the license file is not found, the data provider checks for keys placed in the registry during the installation process; then, the data provider looks for the license key in the installation directory. If the license key is not found, the data provider fails to connect.

Example

C:\install_dir\DDTek.lic

Default

An empty string.

Category

Advanced

Load Balance Timeout

Property

LoadBalanceTimeout

Description

Specifies the minimum number of seconds to keep connections in a connection pool before destroying them. The Min Pool Size option can cause some connections to ignore this value.

Valid Values

0 | x

where x is a positive integer from 1 to 65535.

If set to 0, the lifetime is never limited by time.

See Removing Connections from a Pool for a discussion of connection lifetimes.

Alias

Connection Lifetime

Default

0

Category

Connection Pooling

Load Balancing

Property

LoadBalancing

Description

Determines whether the data provider uses client load balancing in its attempts to connect to primary and alternate database servers. The list of alternate servers is specified by the Alternate Servers connection option.

Valid Values

True | False

If set to True, the data provider attempts to connect to the database servers in random order. See Client Load Balancing for more information about load balancing.

If set to False, client load balancing is not used and the data provider connects to each 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 string option.

The Load Balancing connection string option is an optional setting that you can use in conjunction with connection failover. See Using Connection Failover for a discussion of connection failover and for information about other connection options that you can set for this feature.

Default

False

Category

Failover

Max Pool Size

Property

MaxPoolSize

Description

Specifies the maximum number of connections within a single pool. When the maximum number is reached, no additional connections can be added to the connection pool. The Max Pool Size Behavior option can cause this option to be ignored during periods of high demand.

See Creating a Connection Pool for more information.

Valid Values

An integer from 1 to 65535.

Example

If set to 20, the maximum number of connections allowed in the pool is 20.

Default

100

Category

Connection Pooling

Max Pool Size Behavior

Property

MaxPoolSizeBehavior

Description

Specifies whether the data provider can exceed the number of connections specified by the Max Pool Size option when all connections in the connection pool are in use.

See Creating a Connection Pool for more information.

Valid Values

SoftCap | HardCap

If set to SoftCap, when all connections are in use and another connection is requested, a new connection is created, even when the connection pool exceeds the number set by the Max Pool Size option. If a connection is returned and the pool is full of idle connections, the pooling mechanism selects a connection to be discarded so the connection pool never exceeds the Max Pool Size.

If set to HardCap, when the maximum number of connections allowed in the pool are in use and a new connection is requested, the connection request is queued. If no connection becomes available before the Connection Timeout is reached, the data provider terminates the attempt and generates an error.

Default

HardCap

Category

Connection Pooling

Max Statement Cache Size

Property

MaxStatementCacheSize

Description

Specifies the maximum number of cached statements that can be associated with the current connection.

Valid Values

0 | x

where x is a positive integer greater than 1.

If set to 0, statement caching is disabled.

This connection string option can affect performance. See Performance Considerations for more information.

Default

10

Category

Performance

Min Pool Size

Property

MinPoolSize

Description

Specifies the number of connections created when a connection pool is initialized and the minimum number of connections that will be kept in the pool. The connection pool retains this number of connections, even when some connections exceed their Load Balance Timeout value.

See Removing Connections from a Pool for a discussion of connection lifetimes.

Valid Values

0 | x

where x is a positive integer from 1 to 65535.

If set to 0, no additional connections are placed in the connection pool when it is created.

Default

0

Category

Connection Pooling

Number As Double

Property

NumberAsDouble

Description

Determines whether the Oracle NUMBER data type with no precision and no scale is mapped to DOUBLE.

Note: This property is useful for standard ADO.NET applications. However, it is not accessible from the ADO.NET Entity Framework. Instead, the data provider uses the Entity Framework programming contexts.

Valid Values

True | False

If set to True, the Oracle NUMBER data type with no precision and no scale is mapped to DOUBLE.

If set to False, the Oracle NUMBER data type with no precision and no scale is not mapped to DOUBLE.

Default

False

Category

Advanced

Packet Buffer Size

Property

PacketBufferSize

Description

Specifies the number of bytes used for the buffer used to read packets from the network socket that is communicating with the Oracle database. Increasing the buffer size often improves performance for applications that have large result sets. The packet buffer size should be the same as or smaller than the size set for Fetch Array Size.

Valid Values

An integer from 1 to 2147483648

Default

16000

Category

Performance

Parameter Mode

Property

ParameterMode

Description

Specifies the behavior of native parameter markers and binding. This allows applications to reuse provider-specific SQL code and simplifies migration to the DataDirect data providers.

Valid Values

ANSI | BindByOrdinal | BindByName

If set to ANSI, the ? character is processed as a parameter marker and bound as ordinal. Applications can toggle the behavior of the BindByName property on a per-command basis.

If set to BindByOrdinal, native parameter markers are used and are bound as ordinal for stored procedures and standard commands.

If set to BindByName, native parameter markers are used and are bound by name for stored procedures and standard commands.

Note: When the BindByName property of the OracleCommand object is set to True and this connection string option is defined as BindByName or BindByOrdinal, the value defined in the connection string is overridden for the lifetime of the OracleCommand Class object.

Default

For the ADO.NET data provider, the default is ANSI.

For the ADO.NET Entity Framework data provider, the only supported value is BindByName.

Category

Advanced

Password

Property

Password

Description

Specifies the case-insensitive password used to connect to your Oracle database.

Valid Values

string

where string is a valid password.

Default

An empty string

Category

Security

Persist Security Info

Property

PersistSecurityInfo

Description

Specifies whether to display security information such as the password in clear text in the connection string.

Valid Values

True | False

If set to True, the value of the Password connection string option is displayed in clear text.

If set to False, the data provider does not display the password in clear text in the connection string.

Default

False

Category

Security

Pooling

Property

Pooling

Description

Specifies whether connections are pooled.

Valid Values

True | False

If set to False, connection pooling is not enabled.

If set to True, connection pooling is enabled. See Using Connection Pooling for a discussion of connection pooling.

Default

True

Category

Connection Pooling

Port

Property

Port

Description

Specifies the TCP port of the Oracle listener running on the Oracle database.

Valid Values

port

where port is the port number.

Default

1521

Category

Standard Connection

Procedure Description Cache

Property

ProcedureDescCache

Description

Determines whether the stored procedure information is cached.

Valid Values

True | False

If set to False, the stored procedure information is not cached. Applications that change stored procedure definitions during runtime should use this setting to disable this cache.

If set to True, the Oracle data provider caches stored procedure information it obtains from the server to efficiently support the REF CURSOR parameter.

Default

True

Category

Performance

Program ID

Property

ProgramID

Description

Specifies the value of the PROCESS column in the V$SESSION table.

Valid Values

string

where string is the value that identifies the Client Product Version/ID on the server.

Default

An empty string

Category

Client Monitoring

Reauthentication Enabled

Property

ReauthenticationEnabled

Description

Determines whether the data provider can reauthenticate a connection, that is, perform a proxy authentication, in a pooled connection environment. A physical connection involves a socket to the server with its negotiated connection state with the server. When a user logs on to the server, the server establishes a session.

Valid Values

True | False

If set to True, the data provider checks the credentials of the OS authenticated user requesting a connection, and reassigns a connection enabled for reauthentication to the user. When the user is changed, an additional session is established for the new user. This means that in the V$SESSION table, a single connection lists User1 and User2 in separate sessions.

If set to False, the data provider does not reauthenticate users in a pooled connection environment. Each user has a different connection string and a different connection pool.

Default

False

Category

Security

Ref Cursor Mode

Property

RefCursorMode

Description

Specifies how the data provider processes REF CURSORs. Setting this option to Explicit or ExplicitWithInfo provides portability for applications that were built with Oracle data providers supplied by database vendors (ODP.NET), and by the .NET Framework (the .NET Framework Data Provider for Oracle).

Valid Values

Implicit | Explicit | ExplicitWithInfo

If set to Implicit, parameters are not specified as REF CURSORs. The data provider throws an InvalidOperationException exception if the application attempts to use the RefCursor description.

If set to Explicit, parameters must be specified with an OracleDbType.RefCursor when describing the parameters to be used.

If set to ExplicitWithInfo, parameters must be specified with an OracleDBType.RefCursor when describing parameters. The data provider uses an additional round trip to ensure the type safety of the parameters.

Notes:

• When the Ref Cursor Mode connection string option is set to Explicit or ExplicitWithInfo, the Value property of the Ref Cursor Parameter object must either be null or set to DBNull.Value.
• When the Parameter Mode connection string option is set to BindByName or BindByOrdinal, the data provider can support output parameters and Ref Cursor on anonymous PL/SQL blocks.
• This property is useful for standard ADO.NET applications. However, it is not accessible from the ADO.NET Entity Framework. Instead, the data provider uses the Entity Framework programming contexts.

Default

Implicit

Category

Advanced

Schema Collection Timeout

Property

SchemaCollectionTimeout

Description

Specifies the number of seconds after which an attempted schema collection operation fails if it is not yet completed.

Valid Values

A positive integer 1 or higher.

Default

120

Category

Schema Information

Schema Options

Property

SchemaOptions

Description

Specifies additional database metadata that can be returned. By default, the data provider prevents the return of some available database metadata to optimize performance. If your application needs this database metadata even though returning it is performance-expensive, specify the name or hexadecimal value of the metadata.

This option can affect performance (see Performance Considerations).

Valid Values

If set to ShowDescriptions or 0x01, descriptions of tables and columns are returned.

If set to IncludeSynonyms or 0x02, synonyms for tables, table privileges, indexes, and primary keys are returned.

If set to ShowColumnDefaults or 0x04, column defaults are returned.

If set to ShowProcedureDefinitions or 0x20, procedure definitions are returned.

If set to ShowViewDefinitions or 0x40, view definitions are returned.

If set to ShowAll or 0xFFFFFFFF, all database metadata is returned.

To show more than one piece of the omitted database metadata, specify either a comma-separated list of the names, or the sum of the hexadecimal values of the metadata that you want to return.

The following table lists the names and hexadecimal values you can specify to increase the amount of database metadata returned.

Oracle Column Collections

¹ COLUMN_HAS_DEFAULT is always reported with a value of null.

Example

For example, to return descriptions of tables and columns, specify Schema Options=ShowDescriptions or Schema Options=0x01.

To show more than one piece of the omitted metadata, specify either a comma-separated list of the names, or the sum of the hexadecimal values of the metadata that you want to return. For example, to return descriptions of the Tables and Columns collections, and the procedure definitions (hexadecimal values 0x01 and 0x20, respectively), specify one of the following:

Schema Option=ShowDescriptions, ShowProcedureDefinitions
Schema Options=0x21

Default

0x40 or ShowViewDefinitions

Category

Schema Information

Server

Property

Server

Description

Specifies a connection string value based on the format used in the tnsnames.ora file.

Note: The Server connection string option cannot be used in the same connection string that uses any of the following connection string options: Host, Port, SID, Service Name, Server Type, Alternate Servers, SessionDataUnit, LoadBalancing and EncryptionMethod.

Valid Values

string

where string is the connection string.

Example

Server=(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(Host=server3)(PORT=1521))(CONNECT_DATA=(SID=ORCL)));

Default

An empty string

Category

TNSNames Connection

Server Type

Property

ServerType

Description

Specifies whether the connection is established using a shared or dedicated server process. If the server is configured for Dedicated, the application must specify Dedicated. If the server is set to Shared, the application can specify either Dedicated or Shared.

Valid Values

An empty string | Shared | Dedicated}

If set to Shared, the server process to be used is retrieved from a pool. The socket connection between the client 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; however, communication is slower. Use this value when a server must handle a large number of clients.

If set to Dedicated, a server process is created to service only that connection. When that connection ends, so does the process. The socket connection is made directly between the application and the dedicated server process.

If set to an empty string, the data provider 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 data provider to be able to specify the shared server process type.

Default

An empty string

Category

Standard Connection

Service Name

Property

Service Name

Description

Specifies the database 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.

This property is useful to specify connections to an Oracle Real Application Clusters (RAC) system rather than a specific Oracle instance because the nodes in a RAC system share a common service name.

Note: If using a tnsnames.ora file to provide connection information, or using the SID or Data Source connection string options, do not specify Service Name.

Valid Values

service_name

where service_name is the description of the destination for a network connection.

Example

sales.us.acme.com 

Default

An empty string

Category

Standard Connection

Session Data Unit

Property

SessionDataUnit

Description

Specifies the session data unit (SDU) that will be requested when connecting to the server. The SDU is essentially equivalent to the maximum packet size. The actual SDU that will be used is negotiated with the server. For optimal performance, set this option to the maximum SDU size configured on the database server.

This connection string option can affect performance. See Performance Considerations for more information.

Valid Values

An integer from 512 to 32767.

Default

16384

Category

Standard Connection

SID

Property

SID

Description

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

Note: If using a tnsnames.ora file to provide connection information, or using the SID or Data Source connection string options, do not specify Service Name.

Valid Values

sid

Default

An empty string. The data provider uses the Oracle default SID when installing the Oracle database software.

Category

Standard Connection

Statement Cache Mode

Property

StatementCacheMode

Description

Specifies the statement caching mode for the lifetime of the connection. See Using Statement Caching for more information.

Valid Values

Auto | ExplicitOnly

If set to Auto, statement caching is enabled for statements marked as Implicit by the Command property StatementCacheBehavior. These commands have a lower priority than that of explicitly marked commands, that is, if the statement pool reaches its maximum number of statements, the statements marked implicit are removed from the statement pool first to make room for statements marked Cache.

If set to ExplicitOnly, only commands that are marked Cache by the StatementCacheBehavior property are cached.

Notes:

• ExplicitOnly is the only valid value for the Entity Framework data provider.
• To enable statement caching for existing applications that use the DataDirect Connect for ADO.NET 3.1 data providers without changing any application code, set Statement Cache Mode to Auto. All statements are eligible to be placed in the statement cache.

This connection string option can affect performance. See Performance Considerations for more information.

Default

ExplicitOnly

Category

Performance

Support Links

Property

SupportLinks

Description

Determines whether the data provider supports Oracle linked servers, which means a mapping has been defined in one Oracle server to another Oracle server. In most cases, setting this connection string option to False provides the best performance.

Note: If the Support Links connection string option is enabled, do not enable the Enlist connection string option.

Valid Values

True | False

If set to True, the data provider supports Oracle linked servers, and does not support distributed transactions.

If set to False, the data provider does not support Oracle linked servers, and does support distributed transactions.

Default

False

Category

Advanced

Synchronize Connection

Property

SynchronizeConnection

Description

Specifies whether synchronization on the connection is required. Typically, this is only needed if a connection is being shared across multiple threads.

Valid Values

True | False

Default

False

Category

Advanced

TNSNames File

Property

TNSNamesFile

Description

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 alias or Oracle net service name. Using the TNSNames File option lets you construct a shorter connection string because the connection information is in tnsnames.ora.

Note: This property is useful for standard ADO.NET applications. However, it is not accessible from the ADO.NET Entity Framework. Instead, the data provider uses the Entity Framework programming contexts.

Valid Values

A valid path name.

If set to an empty string, the path to the tnsnames.ora file is not specified.

To specify multiple tnsnames.ora file locations, separate the names with a comma and enclose the locations in single or double quotation marks.

Example

TNSNames File="F:\server2\oracle\tnsnames.ora, C:\oracle\product\10.1.0\db_1\network\admin\tnsnames.ora"

Default

An empty string

Category

TNSNames Connection

Trace File

Property

TraceFile

Description

Specifies the path and name of the trace file. If the specified trace file does not exist, the data provider creates it.

Valid Values

A valid path name

Example

\OracleTrace.txt

Default

An empty string

Category

Tracing

Transaction Timeout

Property

TransactionTimeout

Description

Specifies the length of time (in seconds) that the data provider waits when committing or rolling back a transaction.

Valid Values

0 | -1 | x

where x is any positive integer.

If set to 0, the data provider never times out.

If set to x, the data provider waits the specified number of seconds before committing or rolling back the transaction.

If set to -1, the data provider uses the value specified for the Connection Timeout connection string option.

Default

-1

Category

Advanced

Use Current Schema

Property

UseCurrentSchema

Description

Specifies whether the results are restricted to tables or views in the current schema of the GetSchema method of the DbConnection object.

Valid Values

True | False

If set to True, the results returned from any GetSchema call are restricted to tables and views in the current schema.

If set to False, the results returned from a GetSchema call are not restricted to tables and views in the current schema unless the call includes Restrictions parameters.

Default

False

Category

Schema Information

Use Kerberos DotNet

Property

UseKerberosDotNet

Description

Determines whether the data provider uses the Kerberos.NET (a fully managed third-party library) to communicate with the Key Distribution Center (KDC) during authentication in a Kerberos environment.

Valid Values

True | False

If set to True, the data provider uses the Kerberos.NET library to generate Kerberos tickets in a Kerberos environment.

If set to False, the data provider does not use the Kerberos.NET library.

Notes:

• This option is ignored unless the Authentication Method connection string option is set to Kerberos.
• Kerberos.NET is not shipped by Progress DataDirect. It must be obtained independently, for example from the NuGet package manager, and deployed in your application's probing path.
• The exact Kerberos.NET version that DDTek.KerberosHelper.dll was built and tested against is documented in the product installation directory, under net40\DEPENDENCIES_DDTek.KerberosHelper.md.

Default

False

Category

Security

User ID

Property

UserID

Description

Specifies the default user name used to connect to your Oracle database.

Valid Values

string

where string is a valid user name.

Example

Scott

Default

An empty string

Category

Security

User ID Privilege

Property

UserIDPrivilege

Description

Specifies the role to use when logging in as a database administrator. Typically, this connection string option should be enabled only for connections used by database administrators.

Valid Values

SYSDBA | SYSOPER | None

If set to SYSDBA, the application or user connects to an Oracle server with SYSDBA administrative privileges.

If set to SYSOPER, the application or user connects to an Oracle server with SYSOPER administrative privileges.

If set to None, the connection does not have administrative privileges.

Alias

DBA Privilege, Login Role

Default

None

Category

Security

Validate Server Certificate

Property

ValidateServerCertificate

Description

Specifies whether the data provider must verify the server certificate as valid according to a Certificate Authority.

Valid Values

True | False

If set to True, the data provider validates the server certificate during authentication.

If set to False, no certificate verification is required during authentication.

Default

True

Category

Security

Wire Protocol Mode

Property

WireProtocolMode

Description

Specifies whether the data provider optimizes network traffic to the Oracle server for result sets containing repeating data.

Valid Values

1 | 2

If set to 1, the data provider operates in normal wire protocol mode without optimizing network traffic for result sets.

If set to 2, the data provider optimizes network traffic to the Oracle server for result sets containing multiple rows that have repeating data in some or all of the columns. If a column contains identical data across multiple consecutive rows in the result set, setting this option to 2 can greatly improve performance of fetching the data. Setting this option to 2 may degrade performance for single row result sets or result sets that do not contain repeating data.

Default

1

Category

Performance

Work Arounds

Property

WorkArounds

Description

This option is reserved. Enter values only when directed by Progress Customer Support.

Default

0

Category

Advanced

Functionality Differences for the Oracle Entity Framework Data Provider

Note: Some connection string options are not supported in the ADO.NET Entity Framework. However, the functionality is provided a different way.However, the functionality is provided through the use of pseudo stored procedures. see Using Pseudo Stored Procedures for more information.

See Changes in Default Values for Connection String Options and Supported Properties and Methods for other differences.