ExecuteNonQueryAsync(CancellationToken) Method

A Task-based asynchronous version of the TdCommand.ExecuteNonQuery method. The cancellation token may be use to cancel the execution of the TdCommand.

Syntax

Visual Basic
C#
C++/CLI

'Declaration
 
Public Overloads Overrides NotOverridable Function ExecuteNonQueryAsync( _
   ByVal cancellationToken As CancellationToken _
) As Task(Of Integer)

'Usage
 
Dim instance As TdCommand
Dim cancellationToken As CancellationToken
Dim value As Task(Of Integer)
 
value = instance.ExecuteNonQueryAsync(cancellationToken)

public override Task<int> ExecuteNonQueryAsync( 
   CancellationToken cancellationToken
)

public:
Task<int>^ ExecuteNonQueryAsync( 
   CancellationToken cancellationToken
) override

Parameters

cancellationToken

Return Value

Returns a Task<Int32> with the number of rows affected (Activity Count). The number of rows affected is only returned for DELETE, INSERT, and UPDATE statements. For all other statements, the activity count that is returned will be -1.

Exceptions

Exception	Description
System.InvalidOperationException	Can be thrown because of one of the following errors: 1) TdCommand.Connection is not in Open state or is null. 2) TdCommand.CommandText is null or empty. 3) `TdCommand` has an open DataReader. 4) `TdCommand` has an active request. 5) The local transaction associated with `TdCommand` is not the same as the local transaction associated with `TdConnection`. Assign the local transaction to the TdCommand.Transaction property.
System.ObjectDisposedException	The `TdCommand` is closed / disposed.
TdException	.NET Data Provider for Teradata detected an error.

Remarks

Executes a SQL statement and returns a Task<Int32> with the Activity Count. Teradata always returns an Activity Count which reflects the number of rows affected for UPDATE, DELETE and INSERT statements. ExecuteNonQueryAsync returns the sum of all activity counts if TdCommand represents a multi-statement request. For example, ExecuteNonQueryAsync returns 3 if a multi-statement request that contains three INSERT statements is executed.

If the activity count overflows Int32.MaxValue, Int32.MaxValue value will be returned. The provider will post an event to TdConnection.InfoMessage when an overflow condition occurs. The event will include a warning code and message. The warning message will have the actual activity count. The message code is 111002 and the message text is "An overflow occurred while calculating the activity count, actual value is [ActivityCount]"

NOTE: In order for an application to be aware that an overflow occurred, it must register for the callback with TdConnection.InfoMessage event.

When the CommandType is set to StoredProcedure, any output parameters are populated with data.

If this function generates a runtime exception, that exception will be wrapped in an AggregateException within the returned Task:

Exception	Description
IndexOutOfRangeException	Can be thrown because of one of the following errors: 1) The TdParameter.Offset is outside of 0 through array size � 1 2) More in-out/out parameters have been specified than returned from the stored procedure.
InvalidCastException	One or more parameters cannot be converted to the Advanced SQL Engine native types.
OperationCanceledException	The asynchronous operation was canceled.
TdException	The Advanced SQL Engine returned an error, or .NET Data Provider for Teradata detected an error.

Example

The following example creates a TdConnection and asynchronously executes a SQL statement. See the example for TdCommand.ExecuteNonQuery about handling the activity count overflow.

public int ExecuteQueryAsync(string connectionString, string commandText)
{
    // Open a session to Teradata
    using (TdConnection cn = new TdConnection(connectionString))
    {
        cn.Open();
        
        // Execute the command
        using (TdCommand cmd = new TdCommand(commandText, cn))
        {
            CancellationTokenSource cts = new CancellationTokenSource();
            
            // Cancel the command if it doesn't complete in 20 seconds
            cts.CancelAfter(20000);
            
            Task<Int32> task;
            
            try 
            {
                task = cmd.ExecuteNonQueryAsync(cts.Token);
            } 
            catch (Exception e) 
            {
                // handle programming errors
            }
            
            // perform other tasks
            
            // wait for the Task to complete
            try 
            {
                int activityCount = task.Result;
                
                // Return the activity count
                return activityCount;
            }
            catch (AggregateException ae) 
            {
                // handle task execution errors
            }
        }
    }
}

Requirements

Product	Versions	Platforms
.NET	2.1, 3.1, 6	Windows, Linux, MacOS
.NET Framework	4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8	Windows
.NET Standard	2.0	Windows, Linux, MacOS

Reference

TdCommand Class
TdCommand Members
Overload List