The Data Provider supports setting the following TdConnectionStringBuilder.Properties using an application configuration file. This allows users to set these properties without recompiling applications. The machine.config file must contain the <teradata.client> Section Group and the <provider> Section Name as described in Configuration Files.
The Data Provider will read the application configuration file after the application defines the TdConnection.ConnectionString properties. Any TdConnectionStringBuilder properties not defined in TdConnection.ConnectionString will be supplemented by the profiles found in the configuration file.
The order in which the TdConnectionStringBuilder properties is set is determined from this table.
| Profile Priority | Description |
|---|---|
| TdConnection.ConnectionString | The values found here have the highest priority when defined in multiple places. For example, a ConnectionTimeout property defined in the TdConnection.ConnectionString will override the same property found in any ProfileName. |
| Default Profile | When TdConnectionStringBuilder.ProfileName is not defined, a default profile name ("default") if defined in the configuration file will be used to define ConnectionStringBuilder properties not found in the TdConnection.ConnectionString. |
| ProfileName | When a TdConnectionStringBuilder.ProfileName is defined and the profile name is found in the configuration file, the TdConnectionStringBuilder properties not defined in the TdConnection.ConnectionString properties will be used. |
| ProfileName and Default ProfileName | The default ProfileName ("default") may be used to supplement the TdConnectionStringBuilder.ProfileName properties. Properties not found in the ProfileName and not found in the TdConnection.ConnectionString will be supplied from the default ProfileName if it exists. |
The following is an example of several profile names and a "default" profile name as it appears in an application configuration file. The TdConnectionStringBuilder.ProfileName defines which profile name to read and set the TdConnectionStringBuilder properties. If the ProfileName is not found within the application configuration file <profiles> section, an error indicating an invalid connection string attribute will be returned.
| Application Configuration File Provider Section Group Example |
Copy Code |
|---|---|
<?xml version="1.0"?> <configuration> <teradata.client> <provider> <profiles> <add name="TacticalQuery" ConnectionTimeout="10" CommandTimeout="40" /> <add name="default" ConnectionTimeout="25" CommandTimeout="60" /> <add name="extended" ConnectionTimeout="40" CommandTimeout="100" RecoveryCommandTimeoutOverride="true" RecoveryStartInterval="1" ConnectMaxRetryCount="150" RecoveryIntervalFactor="1" RecoveryMaximumInterval="25" /> </profiles> </provider> </teradata.client> <!-- Other sections and section groups. --> </configuration> | |
The definitions for each of the configuration elements are as follows:
| Element Name | Description |
|---|---|
| <teradata.client> | Element that indicates that the content is for the .NET Data Provider for Teradata. |
| <provider> | Indicates that the information is related to the Data Provider. |
| <profiles> | Indicates a list of profiles follows. |
| <add> | Adds a profile containing values which are read during startup of an application. The values will override the default values supplied by the Data Provider. |
The <add> element supports the following attributes:
| Attribute Name | Default Value | Description |
|---|---|---|
| name | none | The name of the profile containing the supported TdConnection.ConnectionString properties. |
| ConnectionTimeout | 20 (seconds) | This represents the time to wait for establishment of a connection before terminating the attempt. |
| ConnectMaxRetryCount | 200 | The connection maximum retry count. This represents the maximum number of retries of opening a connection until an error is returned to the application. |
| CommandTimeout | 30 (seconds) | This sets the default command timeout. The Data Provider sets this value internally to 30 seconds. |
| HttpsPortNumber | 443 | Specifies the HTTPS port number to use when establishing a TLS-encrypted connection to the Teradata Gateway. |
| RecoveryTimeout | 1200 (seconds) | The reconnection timeout before terminating reconnection. The RecoveryTimeout is used when the command timeout is 0, or the RecoveryCommandTimeoutOverride is true when using synchronous commands. Asynchronous commands will always use the RecoveryTimeout during reconnection. |
| RecoveryCommandTimeoutOverride | True (Boolean) | All synchronous commands that contain a zero (infinite) CommandTimeout will always extend the reconnection time by the RecoveryTimeout. If the command timeout is non-zero, this new override property (when true) will also extend the reconnection time by adding the RecoveryTimeout value. |
| RecoveryStartInterval | 2 (seconds) | The recovery starting interval time (in seconds). This represents the time between retrying a reconnection attempt. |
| RecoveryIntervalFactor | 2 (seconds) | The recovery interval factor. This represents the adjustment in the recovery interval period from the preceeding interval period. The factor is a additive factor. |
| RecoveryMaximumInterval | 32 (seconds) | The recovery maximum interval. This represents the maximum interval time, used to limit the retry interval time adjusted by the RecoveryIntervalFactor. |
| SslMode | "Prefer" (String) | Specifies the SslMode. |
| ResponseBufferSize | 524288 (bytes) | Specifies the ResponseBufferSize. |
| UseXViews | True (Boolean) | Specifies the UseXViews value. |
The following properties enable an application to change internally within the Data Provider the behavior during reconnection attempts (when enabled in TdConnectionStringBuilder.Recovery). They are values that are used in algorithms to define the Data Provider retryable behavior.
RecoveryTimeout will provide existing applications an opportunity to change the RecoveryTimeout value used in reconnection efforts in the case of a network error or an Advanced SQL Engine failure. If the CommandTimeout is 0, the reconnection timeout will always be extended by the RecoveryTimeout value in the application configuration file or the default value if not provided in the application configuration file. If the CommandTimeout is non-zero, the RecoveryCommandTimeoutOverride will extend the reconnection timeout by the RecoveryTimeout value when it is true. The TdConnection.RecoverConnection event will use this RecoveryTimeout value if the application has not provided a value for the TdRecoveryEventArgs.RecoveryTimeout in the event arguments. If the event is activated again because the default RecoveryTimeout expired, and the application is not listening, no additional time will be provided for reconnection and the reconnection will fail.
RecoveryCommandTimeoutOverride will extend the reconnection timeout RecoveryTimeout when the a synchronous CommandTimeout is a finite value. Applications may enforce the original CommandTimeout value by setting the RecoveryCommandTimeoutOverride to false. Any recovery operations due to network or SQL Engine failures will not be extended beyond the original CommandTimeout.
RecoveryStartInterval is used only during reconnection efforts and is defined as the first time period to wait between unsuccessful efforts to retry or reconnect. It is used to retry reconnection attempts. If the RecoveryIntervalFactor is 0, the RecoveryStartInterval will be used to delay for all retryable attempts, as the RecoveryIntervalFactor will not change the delay period.
RecoveryIntervalFactor will modify the RecoveryStartInterval to create a new period of time to delay attempts to reconnect to the SQL Engine. The RecoveryMaximumInterval will limit the upper value of this period of time. For example, if the RecoveryStartInterval is 2, the RecoveryIntervalFactor is 2 and the RecoveryMaximumInterval is 32, the time periods generated internally will be 2, 4, 8, until the maximum delay period of 32 seconds is reached.
RecoveryMaximumInterval is the maximum interval of time to wait between attempts to reconnect to the SQL Engine. If a RecoveryIntervalFactor has been defined, the RecoveryMaximumInterval will set the upper limit that may be used to delay attempts.
ConnectMaxRetryCount will set the maximum number of retries of a connection attempt. Once this limit is reached, the connection will fail. For example if the value is set to 200, the Data Provider will retry 200 times before failing the connection attempt.