Class TigerQueryEngineOptions

Namespace

ItTiger.TigerQuery.Engine

Assembly

ItTiger.TigerQuery.dll

Configures parsing, SQL execution, variables, logging, and synchronous callbacks for a TigerQueryEngine.

public sealed class TigerQueryEngineOptions

Inheritance

object

TigerQueryEngineOptions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

An engine reads these options throughout a run. Callback delegates are invoked synchronously on the execution path and should not throw.

Properties

CommandTimeoutSeconds

Gets the SQL command timeout, in seconds, applied to every batch this run executes.

public int? CommandTimeoutSeconds { get; init; }

Property Value

int?

Remarks

This is the batch execution timeout, not the connection-open timeout: the latter belongs to the connection string (Connect Timeout) and is unaffected. The value is applied to each batch independently, so a script of ten batches may run for ten times this long without any batch timing out.

The default is null, which leaves CommandTimeout untouched at the provider's own default of 30 seconds. 0 means no limit and is passed to the provider as such. A negative value is rejected: run methods throw ArgumentOutOfRangeException before opening a connection.

A batch that exceeds the timeout fails the way any other SQL error fails. It counts towards FailedBatches, the effective continue-on-error policy decides whether later batches still run, and the run's ResultCode is not Success.

ConnectionString

Gets the SQL Server connection string used for execution.

public string ConnectionString { get; init; }

Property Value

string

Remarks

Parser-only consumers may leave this empty. Run methods pass it to SqlConnection before opening.

ContinueOnError

Gets the initial policy for continuing after a failed batch execution.

public bool ContinueOnError { get; init; }

Property Value

bool

Remarks

:ON ERROR IGNORE and :ON ERROR EXIT update this policy for subsequent parser-produced batches. Fatal SQL errors always stop execution.

A batch fails when SQL Server reports an error of severity 11 or higher for it, whether the provider throws or reports the error as an informational message. Under an effective exit-on-error policy the triggering batch ends unsuccessfully and no further batch is started. Under an effective continue policy the batch still counts towards FailedBatches and the next scheduled batch runs.

This policy controls how much of the script runs, not what the run reports. Either way the run's ResultCode is not Success once any batch attempt has failed.

ContinueOnErrorForUnhandledExceptions

Gets whether non-SQL exceptions caught during batch execution may be ignored when the effective continue-on-error policy is enabled.

public bool ContinueOnErrorForUnhandledExceptions { get; init; }

Property Value

bool

Remarks

The default is false. TigerQueryException and exceptions raised outside the batch execution catch path are never made continuable by this option.

EnableTransaction

Gets a reserved transaction preference.

public bool EnableTransaction { get; init; }

Property Value

bool

Remarks

The current engine does not create or manage a transaction from this option. It is retained for API compatibility.

ExecutionMode

Gets whether parsing is interleaved with SQL execution or completed before the SQL connection is opened.

public TigerQueryExecutionMode ExecutionMode { get; init; }

Property Value

TigerQueryExecutionMode

Remarks

Streaming is the default and retains only the current logical batch. Prepared retains every expanded logical batch until execution completes.

Logger

Gets the optional destination for structured engine diagnostics.

public ILogger? Logger { get; init; }

Property Value

ILogger

Remarks

The engine does not dispose the logger.

Mode

Gets the parser mode that controls sqlcmd directives and variable support.

public SqlCmdMode Mode { get; init; }

Property Value

SqlCmdMode

OnBatchEnd

Gets a callback invoked after each started batch execution attempt.

public Action<BatchEnd>? OnBatchEnd { get; init; }

Property Value

Action<BatchEnd>

Remarks

SQL messages and result-set callbacks may occur after batch start and before batch end. Callback exceptions are not a supported control-flow mechanism and are not guaranteed to be converted into an ExecutionResult.

OnBatchStart

Gets a callback invoked immediately before each batch execution attempt.

public Action<BatchStart>? OnBatchStart { get; init; }

Property Value

Action<BatchStart>

Remarks

Repeated batches raise this callback once per positive repeat iteration. It is not raised for zero or negative repeat counts.

OnExecutionPlanReady

Gets a callback invoked once in prepared mode after the complete TigerQuery/sqlcmd structure has been parsed successfully and before the SQL connection is opened.

public Action<ExecutionPlanReady>? OnExecutionPlanReady { get; init; }

Property Value

Action<ExecutionPlanReady>

Remarks

This callback is not raised in streaming mode or when preparation fails or is cancelled. An empty prepared script raises it with zero counts. Cancellation is checked immediately before and after invocation; if the callback cancels the supplied run token, no connection or batch callback follows.

OnMessage

Gets a callback for SQL Server messages and exceptions observed during execution.

public Action<SqlCmdMessage, bool>? OnMessage { get; init; }

Property Value

Action<SqlCmdMessage, bool>

Remarks

The Boolean argument is true when the message was raised while handling an exception. Server messages delivered by the provider use false, including error diagnostics, which the provider reports that way for severities 11 through 16. The callback can occur between matching batch-start and batch-end callbacks. A diagnostic that the provider delivers both as a message and on a thrown exception for the same attempt is raised once.

OnResultSet

Gets a callback for each fully materialized SQL result set.

public Action<ResultSetInfo>? OnResultSet { get; init; }

Property Value

Action<ResultSetInfo>

Remarks

The callback runs before the matching batch-end callback. Each payload and its row arrays are newly allocated for that result set and are not reused or mutated by the engine after delivery, so callers may retain them.

OutputRouting

Gets the script-directed output routing and file-output configuration.

public OutputRoutingOptions OutputRouting { get; init; }

Property Value

OutputRoutingOptions

Remarks

The default routes every channel to the callbacks below and creates no files. Invalid routing configuration fails at run start, before parsing, connection opening, or output-file creation.

Variables

Gets programmatic variables available before script parsing begins.

public IDictionary<string, string>? Variables { get; init; }

Property Value

IDictionary<string, string>

Remarks

Names are matched case-insensitively. In SqlCmd, these values seed the variable table and :setvar may replace them. In SqlCmdEx, they take precedence and assignments to matching names are ignored; non-conflicting script-local variables can still be created and updated. Programmatic variables are ignored in Normal.