B Connection String Option Descriptions : SQL Server Data Provider Connection String Options

SQL Server Data Provider Connection String Options
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.
The connection string option name and the property name are the same; however, the spaces in the connection string option name are required.
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 SQL Server data provider, you must specify the name or the IP address of each alternate server and the port number; alternatively, you can specify the Server connection string option.
See “Using 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:
Host=server2;Port=1433, server=server_name\server_instance
Default
An empty string
Category
Failover
Always Report Trigger Results
Property
AlwaysReportTriggerResults
Description
Determines how the data provider reports results generated by database triggers (procedures that are stored in the database and executed, or fired, when a table is modified).
Valid Values
True | False
If set to True, the data provider returns all results, including results generated by triggers. Multiple trigger results are returned one at a time. Warnings and errors are reported in the results as they are encountered.
If set to False, the data provider does not report trigger results if the statement is a single INSERT, UPDATE, or DELETE statement. In this case, the only result that is returned is the update count generated by the statement that was executed (if errors do not occur). Although trigger results are ignored, any errors generated by the trigger are reported. Any warnings generated by the trigger are enqueued. If errors are reported, the update count is not reported.
Default
False
Category
Misc
Application Name
Property
ApplicationName
Description
Specifies the name that the SQL Server server uses to identify the client application.
Valid Values
string
where string is the name of the application.
Default
NULL
Category
Misc
Authentication Method
Property
AuthenticationMethod
Description
Determines which authentication method the data provider uses when establishing a connection.
Valid Values
UserIDPassword | Kerberos | NTLM
If set to UserIDPassword or if no value is set, the data provider uses the SQL Server user ID/password authentication. If a user ID and password are not specified, the data provider throws an exception.
If set to Kerberos, the data provider uses Kerberos authentication. The data provider ignores any user ID or password specified.
If set to NTLM, the data provider uses NTLM authentication. Values specified for the User ID and Password properties are ignored.
Default
UserIDPassword
Category
Security
Clone Connection if Needed
Property
CloneConnectionifNeeded
Description
Determines whether the data provider clones the existing connection if another active result set is not currently possible on the existing SQL Server connection and the application requires one. This connection string option can affect performance. See “Performance Considerations” for more information.
NOTE: Reauthentication cannot be performed on connections that can be cloned (see Reauthentication Enabled).
Valid Values
True | False
If set to True, the data provider clones the connection.
If set to False, the data provider does not clone the connection.
Default
False
Category
Performance
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.
Valid Values
0 | x
where x is a positive integer greater than 1.
Default
15
Category
Connection Pooling
Database Name
Property
DatabaseName
Alias
Database. If both the Database and Database Name connection string options are specified, the value specified for the Database Name is used.
Description
Specifies the name of the database to which you want to connect. If you do not specify a value, the default is the database defined by the system administrator for each user.
Valid Values
string
where string is the name of a database.
Default
An empty string
Category
Standard Connection
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
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 | LoginSSL
If set to NoEncryption, data sent between the data provider and the SQL Server server is not encrypted.
If set to SSL, all data sent between the data provider and the database 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 set to LoginSSL, the login request uses SSL encryption if the server requires SSL encryption. If the server does not support SSL encryption, the login request is unencrypted.
NOTES:
Default
NoEncryption
Category
Security
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 Buffer Size
Property
FetchBufferSize
Description
Specifies the number of bytes of data to prefetch to the client machine when executing a statement that produces a result set. Fetch Buffer Size can limit the actual connection to one active result set if its value is not large enough to hold the entire result set. Having a large buffer is only useful if your application uses more than one active result set per connection, an unusual situation in the .NET programming model.
This connection string option can affect performance for the ADO.NET data provider. For more information, see “Performance Considerations”.
Valid Values
An integer from 1 to 2147483648
Default
1024. We recommend using the default unless your application uses more than one active result set per connection
Category
Performance
Host
Property
Host
Description
Specifies either the name or the IP address of the server to which you want to connect.
Valid Values
string
where string is a valid host name or IP address.
To use a SQL Server server running on the local machine as the application, specify localhost.
NOTE: Do not combine the Host and Server options in a connection string. Supplying multiple terms for the SQL Server server causes the data provider to throw an exception.
Example
If your network supports named servers, you can specify a server name such as SQL Serverserver. Or, you can specify an IP address in IPv4 or IPv6 format or a combination of both. 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 SQLServerCommand class’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.
NOTE: 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.
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:
SQLServerCommand command = new SQLServerCommand();
SQLServerConnection conn = new SQLServerConnection("…; Initial Command Timeout=60; …");
conn .Open();
command.Connection = connection;
// command.CommandTimeout returns 60;
command.CommandTimeout = 45;
// command.CommandTimeout returns 45
command = new SQLServerCommand();
command.CommandTimeout = 45;
command.Connection = conn;
// command.CommandTimeout still returns 45
Default
30
Category
Advanced
Initialization String
Property
InitializationString
Description
Specifies one or more SQL Server commands that are 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 SQL Server server fails. The data provider throws an exception that contains the error returned from the SQL Server server.
Valid Values
command
where command is a SQL command.
Example
The following example is surrounded by double quotation marks because one command contains single quotation marks:
"set ansinull off set ClientName 'SysAdmin' set clienthostname 'DDTEK2345' set clientapplname 'TESTAPP'";…
Default
An empty string
Category
Standard Connection
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 MaxPoolSize 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
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
Packet Size
Property
PacketSize
Description
Determines the number of bytes for each packet transferred from the database server to the client machine. Adjusting the packet size can improve performance. The optimal value depends on the typical size of data inserted, updated, or retrieved by the application, and the environment in which it running. Typically, larger packet sizes work better for large amounts of data. For example, if an application regularly retrieves character values that are 10,000 characters in length, using a value of 32 (16 KB) typically results in improved performance.
To take advantage of this connection string option, you must configure the SQL Server server for a maximum packet size greater than or equal to the value you specified for Packet Size.
For example:
sp_configure "maximum network packet size", 5120reconfigureRestart SQLServer Server
This connection string option can affect performance. See “Performance Considerations” for more information.
Valid Values
-1 | 0 | x
where x is an integer from 1 to 127
If set to -1, the data provider computes the maximum packet size that the database server accepts.
If set to 0, the data provider uses the default packet size configured on the database server.
If set to x, the data provider uses a multiple of 512 bytes (for example, PacketSize=6 means to set the packet size to 6 * 512 = 3072 bytes).
If set to an integer from 128 to 65024, the value indicates the byte count, rounded up to the nearest multiple of 512 if necessary (for example, a value of 175 is rounded up to 512; a value of 1024 requires no rounding).
Default
0
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 SQLServerCommand class 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 SQLServerCommand Class.
Default
ANSI
Category
Advanced
Password
Property
Password
Description
Specifies the case-sensitive password used to connect to your SQL Server database. If a user name is not specified, the data provider uses NTLM authentication when connecting to Microsoft SQL Server. In this case, a password is not required. If a password is required, contact your system administrator to obtain your password.
Refer to the DataDirect Connect Series for ADO.NET Installation Guide for product requirements and configuration that must be satisfied to use Integrated Windows authentication with the SQL Server data provider.
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 SQL Server listener.
Valid Values
port
where port is the port number.
Default
1433
Category
Standard Connection
Reader Close Behavior
Property
ReaderCloseBehavior
Description
Determines whether a Cancel is sent to prevent the server from sending additional rows when Close() is called and the result set has not been fully processed. This option is ignored when the command is a stored procedure.
Valid Values
0 | 1
If set to 1, a Cancel is not sent to prevent the server from sending additional rows.
If set to 0, a Cancel is sent to prevent the server from sending additional rows.
Default
0
Category
Advanced
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.
NOTES:
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.
If set to False, the data provider does not reauthenticate users in a pooled connection environment. All connections use the same connection pool when OS authentication is used.
Default
False
Category
Security
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 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.
Table B-3 provides the supported values for the Schema Options connection string option. To specify multiple values, specify a comma-separated list of the names, or the sum of the hexadecimal values of the column collections that you want to return.
 
Example
To return descriptions of procedure and view definitions, specify
Schema Options=ShowProcedureDefinitions or Schema Options=0x20.
To return procedure definitions and view definitions (hexadecimal values 0x20 and 0x40, respectively), specify
Schema Option=ShowProcedureDefinitions, ShowViewDefinitions or Schema Options=0x60.
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
0x1F
Category
Schema Information
Select Method
Property
SelectMethod
Description
Determines whether server-side database cursors are used for Select statements.
This connection string option can affect performance. For more information, see “Performance Considerations”.
Valid Values
Cursor | Direct
If set to Cursor, server-side database cursors are used.
If set to Direct, Select statements are issued without using server-side database cursors. Direct can be used with multiple open statements and manual transactions. However, if the statement contains a result set larger than the value set in the Fetch Buffer Size option, the connection may have only one active result set. We recommend that you use the default unless you need database cursors.
Default
Direct
Category
Performance
Server
Property
Server
Description
Specifies the name of the section in the Interfaces file that contains the network connection information for the SQL Server database you want to access. The section name typically is the host name of the server that contains the SQL Server database you want to access.
See “Connecting to Named Instances” for a discussion of using named instances.
NOTE: Do not combine the Host and Server options in a connection string. Supplying multiple terms for the SQL Server server causes the data provider to throw an exception. The Port option is not required when using a named instance.
Valid Values
string
where string is the name of the section in the Interfaces file that contains the network connection information.
Default
An empty string
Category
Standard Connection
Text Size
Property
TextSize
Description
Specifies a value that limits the number of bytes of data that can be returned from any single TEXT or IMAGE column in a result set. If the values of the TEXT or IMAGE columns in your application exceed 1 MB, increase this setting to exceed the maximum TEXT or IMAGE value size that you expect.
Valid Values
A positive integer from 1 to 247483647.
Default
1048576
Category
Performance
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
\SQLServerTrace.txt
Default
An empty string
Category
Tracing
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 class.
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
User ID
Property
UserID
Description
Specifies the case-insensitive user name used to connect to your Microsoft SQL Server database. If a user ID is not specified, the data provider uses Integrated Windows authentication (NTLM) when connecting to the database. In this case, a user name is not required. If a user ID is required, contact your system administrator to obtain your user ID.
Valid Values
string
where string is a valid user name.
Example
sa
Default
An empty string
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
Work Arounds
Property
WorkArounds
Description
This option is reserved. Enter values only when directed by Progress Customer Support.
Default
0
Category
Advanced
Workstation ID
Property
WorkstationID
Description
Specifies the name of the client that the data provider specifies to the SQL Server at connection time. This name appears in the output of the SP_who system stored procedure. The value can be useful for database administration purposes.
Valid Values
string
where string is the name of the client.
Default
An empty string
Category
Misc