ExecuteReaderAsync(CommandBehavior,CancellationToken) Method

A Task-based asynchronous version of the TdCommand.ExecuteReader method. Executes the SQL statement (TdCommand.CommandText property) using one of the Data.CommandBehavior enumeration members. The cancellation token may be use to cancel the execution of the TdCommand.

Syntax

Visual Basic
C#
C++/CLI

'Declaration
 
Public Overloads Shadows Function ExecuteReaderAsync( _
   ByVal behavior As CommandBehavior, _
   ByVal cancellationToken As CancellationToken _
) As Task(Of TdDataReader)

'Usage
 
Dim instance As TdCommand
Dim behavior As CommandBehavior
Dim cancellationToken As CancellationToken
Dim value As Task(Of TdDataReader)
 
value = instance.ExecuteReaderAsync(behavior, cancellationToken)

public new Task<TdDataReader> ExecuteReaderAsync( 
   CommandBehavior behavior,
   CancellationToken cancellationToken
)

public:
new Task<TdDataReader^>^ ExecuteReaderAsync( 
   CommandBehavior behavior,
   CancellationToken cancellationToken
)

Parameters

behavior: One of the Data.CommandBehavior enumerations values.
cancellationToken: A Threading.CancellationToken used to indicate that the asynchronous operation should be canceled.

Return Value

Returns a Task<TdDataReader> representing the asynchronous operation.

Exceptions

Exception	Description
System.ComponentModel.InvalidEnumArgumentException	The behavior is not one of the `System.Data.CommandBehavior` enumeration members.
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 static forward-only result set (TdDataReader).

When TdCommand.CommandType is set to StoredProcedure, any output parameters are populated with data. If the stored procedure does not return a dynamic result set, the resulting TdDataReader contains no rows.

Refer to Returning Data of Output Parameters in a Result Set for more information on the execution of stored procedures.

The .NET Data Provider allows more than one TdDataReader object to be open at any given time for each TdConnection. However, there can only be one TdDataReader for each TdCommand. TdDataReader must be closed before TdCommand can execute another SQL statement.

The .NET Data Provider supports In-Line and Deferred LOB retrievals. By default LOBs are retrieved in deferred mode. If the SequentialAccess bit of behavior is turned on, LOBs are retrieved in Inline mode.

behavior can be set to a bit-wise combination of the following CommandBehavior values:

CommandBehavior Member Name	Description
CloseConnection	The associated TdConnection object is closed when the TdDataReader instance is closed.
Default	Sets no `CommandBehavior` flags. Calling `ExecuteReader(CommandBehavior.Default)` is equivalent to calling `ExecuteReader()`.
KeyInfo	Not supported.
SchemaOnly	The SQL statement is prepared and the resulting TdDataReader is used to retrieve schema information (TdDataReader.GetSchemaTable). TdDataReader.Read will return false (no rows). ExecuteReaderAsync will execute the command synchronously.
SequentialAccess	When set, LOBs are returned in-line and they can only be accessed sequentially. See the Advanced SQL Engine documentation for additional information about In-line mode vs. Deferred mode.
SingleResult	The SQL statement returns a single result set. Data.IDataReader.NextResult will return false.
SingleRow	SingleRow does not result in any internal optimization. However, TdDataReader.Read returns false after the first row is read in each result set.

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 executes a SQL statement. It returns a TdDataReader. When the calling method closes the TdDataReader, the corresponding TdConnection is closed.

public TdDataReader ExecuteQuery(string connectionString, string commandText)
{
    TdConnection cn = new TdConnection(connectionString);
    cn.Open();
    
    TdCommand cmd = new TdCommand(commandText, cn);
    TaskCompletionSource tcs = new TaskCompletionSource();
    
    Task<TdDataReader> task = cmd.ExecuteReaderAsync(CommandBehavior.CloseConnection, tcs.Token);
                                    
    // perform other tasks
    
    // wait for the result
    TdDataReader reader = task.Result;
            
    return reader;
}

Requirements

Target Platforms: Windows 8.1, Windows 10, Windows Server 2012 R2, Windows Server 2016, Windows Server 2019

Reference

TdCommand Class
TdCommand Members
Overload List