Configuring Redrive and Recoverable Network Protocol in the .NET Data Provider

Introduction

This blog will introduce the reader to a short description of Redrive and Recoverable Network Protocol in the .NET Data Provider and some of the restrictions that are present in supporting this new feature in the Data Provider. Redrive and RNP is a large topic, and this blog will focus specifically on enabling and configuring Redrive and RNP support in the Data Provider. This includes application configuration file support of new properties that are essential in configuring Redrive and RNP in the Data Provider and using a new TdConnectionStringBuilder.ProfileName to select pre-configured profiles.

Redrive Support in .NET Data Provider 15.1

In Teradata Database Release 14.10 the Redrive Protection Feature enables applications protection from database restarts. Redrive requires Recoverable Network Protocol (RNP) which enables applications to reconnect to the database following a network error or a database failure.  RNP can recover from network errors and re-execute a command or continue retrieving a result set after a reconnect. However after a database restart, the spool files are not preserved (when Redrive is disabled) and data retrieval cannot be continued.

Redrive will attempt to resubmit a command that was executing during a network error or a database failure that caused a reconnection. Teradata will return information to the Data Provider that determines if a command is eligible to be redriven. When Redrive is enabled, the spool files that are generated during a command execution on the database are preserved. This enables commands to be redriven automatically by the Data Provider.

Limitations of Redrive and RNP

1. Redrive and RNP are enabled together as of the current database release (15.0 as of this blog). Applications must logon from the .NET Data Provider and select the ConnectionString property Recovery option "redrive". Selecting the Recovery option "RNP" during logon is not supported by the Teradata Database currently.
2. Redrive contains performance penalties incurred from the database that is used to track requests and store spool files used during Redrive. Consideration must be given to this penalty before enabling Redrive.
3. Requests that cause the database to crash, referred to as killer requests, will not be redriven.
4. Requests that contain deferred LOBs where the TdParameter.Value for the LOB contains a stream or a text reader cannot be redriven.  After a successful reconnection, an exception is returned to the application indicating the request cannot be redriven.
5. Applications that use impersonated single sign-on logons are not supported in RNP or Redrive. The Data Provider does not store the identity from the calling thread, and therefore cannot authenticate the impersonated user.
6. The Teradata Database will not redrive requests from user defined functions or external stored procedures created with the External Data Access clause using the MODIFIES EXTERNAL DATA option. For more information on this limitation refer to the Teradata Database manual "SQL Data Definition Language Detailed Topics".

Enabling Redrive in the .NET Data Provider

A new TdConnectionString property (Recovery) has been added to enable Redrive in applications. The Recovery property contains 4 supported options:

1. Redrive - Enables Redrive and RNP together.
2. RNP - Enables only Recoverable Network Protocol. This is not supported by the database currently.
3. Default - Teradata Active System Management (TASM) sets the participation in Redrive.
4. Off - Disable Redrive and RNP.

An example of this new property using the TdConnectionStringBuilder:

    static void Main(string[] args)
    {
        TdCommand cmd = new TdCommand();
        TdConnection conn = new TdConnection();
        TdConnectionStringBuilder builder = new TdConnectionStringBuilder();
            
        builder.DataSource = "Teradata1";
        builder.UserId = "user1";
        builder.Password = "pass";
        builder.Recovery = "Redrive";
        builder.ProfileName = "profile1";

        TdConnection conn2 = new TdConnection(builder.ToString());

        conn.Open();
    }

Application Configuration File Support

The Data Provider added a new section name (provider) in the application configuration file that supports 8 TdConnection.ConnectionString properties:

1. ConnectionTimeout - Existing property that defines a connection timeout in seconds.
2. ConnectMaxRetryCount - New property that defines the maximum retry count while opening a connection.
3. CommandTimeout - New property to set the default TdCommand timeout. Previously, the property could only be changed by setting the TdCommand.Timeout for each command.
4. RecoveryTimeout - New property that defines a timeout in seconds used only during reconnection.
5. RecoveryCommandTimeoutOverride - New property that enables reconnection for commands with a finite command timeout. The default is true.
6. RecoveryStartInterval - New property defining the starting interval of time in seconds between attempts to reconnect. The default is 2 seconds.
7. RecoveryIntervalFactor - New property defining the additive factor to adjust the RecoveryStartInterval after each reconnection attempt.  The default is 2 seconds.
8. RecoveryMaximumInterval - New property defining the maximum interval in seconds that may be calculated using RecoveryIntervalFactor.

Each of these properties is grouped together within the application configuration file as a property collection accessed by the property group profile collection. A sample section from an application configuration file illustrates the definition of a default profile name and 2 additional profile names.

  <teradata.client>
    <provider>
      <profiles>
        <add name="default"             RecoveryTimeout="1201"             RecoveryCommandTimeoutOverride="true"             RecoveryStartInterval="2"             ConnectMaxRetryCount="199"             RecoveryIntervalFactor="1"             RecoveryMaximumInterval="29"/>
        <add name="profile1"             RecoveryTimeout="1202"             CommandTimeout="32" />
        <add name="profile3"             ConnectionTimeout="65"             RecoveryTimeout="305"             CommandTimeout="35" />
      </profiles>
    </provider>
  </teradata.client>

TdConnection and the new ConnectionString ProfileName

The TdConnection.ConnectionString now contains a new property ProfileName, which enables applications to define a custom profile containing any of the 8 supported ConnectionString properties. These properties were added in the application configuration file primarily for support of RNP and changing the internal behavior of RNP. Through defining a custom profile name, multiple profiles may be defined for different purposes.

There is a reserved profile name ("default") which may be used just as any other profile name. Or it may be used to supplement existing profile names and defaults for TdConnectionString.ConnectionString.

There is a priority in determining ConnectionString properties:

1. The value in the ConnectionString (if the property is specified).
2. The value in the profile name (if the property is specified) specified by the ConnectionString.ProfileName.
3. The value in the "default" profile. Any properties not found in the ConnectionString or in a profile name and defined within the "default" profile will be used for a connection.

Some Examples of ConnectionStrings Using Profiles

All the examples will use the profiles defined in the sample application configuration file shown above.

Example 1

The 1st example sets only the Recovery and ProfileName reconnection ConnectionString properties. The expected RedriveProperties fields are updated with the final properties composed from the ConnectionString, the profile1 profile, and the default profile. The final ConnectionString is composed of the 2 recovery properties from Profile1, the 6 default profile properties and the default properties from the ConnectionString.

        public void Example1()
        {
            TdConnectionStringBuilder builder = new TdConnectionStringBuilder();
            builder.Recovery = "Redrive";
            builder.ProfileName = "profile1";

        }

The resulting ConnectionString properties for Example1:

ProfileName = profile1
CommandTimeout = 32
RecoveryTimeout = 1202
Recovery = REDRIVE
RecoveryCommandTimeoutOverride = True
RecoveryStartInterval = 2
RecoveryIntervalFactor = 1
RecoveryMaximumInterval = 29
ConnectMaxRetryCount = 199
ConnectionTimeout = 20

Example 2

This example illustrates that profile3 is supplemented by the default profile. The expected RedriveProperties is initialized with the contents of the default profile. The expected RedriveProperties fields are updated with the final properties composed from the ConnectionString, the profile3 profile, and the default profile.

        public void Example2()
        {
            TdConnectionStringBuilder builder = new TdConnectionStringBuilder();
            builder.Recovery = "redrive";
            builder.ProfileName = "profile3";

        }

The resultant ConnectionString is composed of the 3 properties of profile3 (ConnectionTimeout, RecoveryTimeout and CommandTimeout) and the remaining properties from the default profile. 

ProfileName = profile3
CommandTimeout = 35
RecoveryTimeout = 305
Recovery = REDRIVE
RecoveryCommandTimeoutOverride = True
RecoveryStartInterval = 2
RecoveryIntervalFactor = 1
RecoveryMaximumInterval = 29
ConnectMaxRetryCount = 199
ConnectionTimeout = 65

Example 3

This example illustrates the priority of the ConnectionString properties over the default profile.  The properties found in the ConnectionString will take priority over the same properties defined within the default profile.

        public void Example3()
        {
            TdConnectionStringBuilder builder = new TdConnectionStringBuilder();
            builder.Recovery = "redrive";
            builder.ConnectionTimeout = 444;
            builder.RecoveryTimeout = 333;
            builder.RecoveryCommandTimeoutOverride = false;
            builder.RecoveryIntervalFactor = 1;
            builder.RecoveryMaximumInterval = 555555;
            builder.ConnectMaxRetryCount = 6666;
            builder.RecoveryStartInterval = 88888;
            builder.CommandTimeout = 999999;
            builder.ProfileName = "default";


        }

All of the Recovery properties are defined only from the ConnectionString, even though the ProfileName specified was "default".

ProfileName = default
CommandTimeout = 999999
RecoveryTimeout = 333
Recovery = REDRIVE
RecoveryCommandTimeoutOverride = False
RecoveryStartInterval = 88888
RecoveryIntervalFactor = 1
RecoveryMaximumInterval = 555555
ConnectMaxRetryCount = 6666
ConnectionTimeout = 444

For more information on Redrive within the Data Provider, please see http://developer.teradata.com/doc/connectivity/tdnetdp/15.01/webhelp/webframe.html#RedriveAndRecoverableNetworkProtocol.html.  This is a link to the 1st page of the new Redrive feature in our on-line documentation for the .NET Data Provider for Teradata 15.01.