Alpha

These pages are built from turborel-cs’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

TurborelCommand

NAME

TurborelCommand: a statement to run on a connection, its dynamic parameters written ?, run directly or prepared, read by a reader or as a scalar.

SYNOPSIS

namespace Turborel.Data;

public sealed class TurborelCommand : DbCommand
{
    public TurborelCommand();
    public TurborelCommand(string commandText, TurborelConnection? connection = null);

    public override string CommandText { get; set; }
    public override int CommandTimeout { get; set; }        // 30
    public override CommandType CommandType { get; set; }   // Text
    public new TurborelConnection? Connection { get; set; }
    public new TurborelTransaction? Transaction { get; set; }
    public new TurborelParameterCollection Parameters { get; }

    public override Task PrepareAsync(CancellationToken cancellationToken = default);
    public override Task<int> ExecuteNonQueryAsync(CancellationToken cancellationToken);
    public override Task<object?> ExecuteScalarAsync(CancellationToken cancellationToken);
    public new Task<TurborelDataReader> ExecuteReaderAsync(CommandBehavior behavior = CommandBehavior.Default,
        CancellationToken cancellationToken = default);
    public override void Cancel();

    // Prepare, ExecuteNonQuery, ExecuteScalar and ExecuteReader wait on the same tasks.
}

DESCRIPTION

CommandText is a statement whose dynamic parameters are written ?, given by Parameters in the order of their marks; a parameter's name is the program's own (TurborelParameter). A command of no parameters, not prepared, runs as one Query: its text one statement or, where the server grants multi-statement, several, split as the server splits them, each statement's result read in turn by the reader's NextResult. A command of parameters is prepared, executed and deallocated. PrepareAsync prepares it once, so each run after executes it with no Prepare; it stays prepared until its text or connection changes, then deallocated as it next runs, and is prepared again on a session renewed, as a pooled connection is given back and taken again. A command made by a data source's CreateCommand runs on a connection of its own, opened from the source and closed with its reader. A query executed opens a cursor, its rows fetched 1000 at a time as the reader reads them (RULES.md D20).

ExecuteReaderAsync gives a reader of the statement's rows as they come (TurborelDataReader); CommandBehavior.CloseConnection closes the connection with it. ExecuteNonQueryAsync runs the statement, reading what it gives, and returns the rows it changed, summed over a Query's statements, or -1 of a query or a statement that counts none. ExecuteScalarAsync returns the first column of the first row, as GetValue gives it, or null of no row.

CommandTimeout is the seconds a statement may run, 0 for no limit: once it runs out before the statement's first reply has come, a cursor's first rows among them, the statement is cancelled on the server, as Cancel cancels it, and fails, SQLSTATE TB920, the session kept. Cancel sends the cancel at once, over a connection of its own. CommandType is Text alone. Transaction, if set, is the connection's transaction.

ERRORS

SQLSTATE SQLCODE When
(the statement's) The server's failure of the statement (Errors)
TB920 -920 The statement cancelled, by Cancel or its timeout
22000 -301 A parameter's value of a type the protocol does not carry
TB910 -910 No connection, or a closed one; Prepare of a command of a data source, which has none; a reader open on the connection; a transaction not the connection's; a CommandType other than Text; a parameter not an input

EXAMPLES

See Running Queries and Prepared Statements of the User's Guide.

STANDARD

ADO.NET's DbCommand, of System.Data.Common; RULES.md D2, D17, D18 and D20. [CLIENT Running statements] and [CLIENT Prepared statements] of The Client Library; [PROTOCOL Query 'Q'], [PROTOCOL Execute 'E'] and [PROTOCOL Fetch 'F'] of The Native Protocol.

SEE ALSO

TurborelDataReader, TurborelParameter, Statements and Cursors.