.NET CORE This feature is not supported by the .NET Core implementation of the Data Provider.

The <provider> Section Name

The Data Provider supports the following TdConnectionStringBuilder.Properties from an application configuration file. This enables applications to set these properties without recompiling an application. The machine.config file must contain the <teradata.client> Section Group and the <provider> Section name as described in Configuration Files.

Accessing TdConnectionStringBuilder Properties in the <provider> Section

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

Example of Profile Definitions in the <provider> Section

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>

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>

Definitions of Elements and Their Attributes

The definition for each of the elements and their attributes are as follows:

Elements and Attributes	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.
name	The name of the profile containing the supported TdConnection.ConnectionString properties.
ConnectionTimeout	This represents the time to wait for establishment of a connection before terminating the attempt.
ConnectMaxRetryCount	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	This sets the default command timeout. The Data Provider sets this value internally to 30 seconds.
RecoveryTimeout	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	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	The recovery starting interval time (in seconds). This represents the time between retrying a reconnection attempt.
RecoveryIntervalFactor	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	The recovery maximum interval. This represents the maximum interval time, used to limit the retry interval time adjusted by the RecoveryIntervalFactor.

Element Default Values

Element Name	Default Value
name	none
ConnectionTimeout	20 (seconds)
ConnectMaxRetryCount	200
CommandTimeout	30 (seconds)
RecoveryTimeout	1200 (seconds)
RecoveryCommandTimeoutOverride	True (Boolean)
RecoveryStartInterval	2 (seconds)
RecoveryIntervalFactor	2 (seconds)
RecoveryMaximumInterval	32 (seconds)

Explanations and Applicability of the Recovery Properties

These 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 a 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.