Table of Contents

Class CdcStalePositionDetector

Namespace
Excalibur.Cdc.SqlServer
Assembly
Excalibur.Cdc.SqlServer.dll

Detects and classifies stale CDC position errors from SQL Server exceptions.

public static class CdcStalePositionDetector
Inheritance
CdcStalePositionDetector
Inherited Members

Remarks

SQL Server reports stale position scenarios through specific error numbers:

  • 22037 - Invalid from_lsn specified for change data capture function
  • 22029 - fn_cdc_get_all_changes was called with a from_lsn that is outside of valid range
  • 22911 - CDC is not enabled for database
  • 22985 - Capture instance not found
  • 313 - Insufficient arguments supplied to CDC TVF (invalid LSN range)

Fields

CaptureInstanceNotFoundError

SQL Server error number for capture instance not found.

public const int CaptureInstanceNotFoundError = 22985

Field Value

int

CdcNotEnabledError

SQL Server error number for CDC not enabled on database.

public const int CdcNotEnabledError = 22911

Field Value

int

InvalidFromLsnError

SQL Server error number for invalid from_lsn in CDC function call.

public const int InvalidFromLsnError = 22037

Field Value

int

LsnOutOfRangeError

SQL Server error number for from_lsn outside valid range.

public const int LsnOutOfRangeError = 22029

Field Value

int

TvfInsufficientArgumentsError

SQL Server error number 313: "An insufficient number of arguments were supplied for the procedure or function".

public const int TvfInsufficientArgumentsError = 313

Field Value

int

Remarks

This error is thrown by cdc.fn_cdc_get_all_changes_* table-valued functions when an invalid LSN range is passed (e.g., a from_lsn that predates the CDC cleanup boundary). While SQL Server typically reports this via errors 22037 or 22029, certain LSN boundary conditions cause the TVF to raise error 313 instead.

Without handling this error, the CDC processor crashes instead of triggering the stale-position recovery path.

Properties

StalePositionErrorNumbers

Gets the set of SQL Server error numbers that indicate a stale CDC position.

public static IReadOnlySet<int> StalePositionErrorNumbers { get; }

Property Value

IReadOnlySet<int>

Methods

CreateEventArgs(Exception, string, byte[]?, byte[]?, string?, string?)

Creates a CdcPositionResetEventArgs from an exception and context.

public static CdcPositionResetEventArgs CreateEventArgs(Exception exception, string processorId, byte[]? stalePosition = null, byte[]? newPosition = null, string? captureInstance = null, string? databaseName = null)

Parameters

exception Exception

The exception that was caught.

processorId string

The identifier of the CDC processor.

stalePosition byte[]

The LSN that was detected as stale.

newPosition byte[]

The new position to resume from, if known.

captureInstance string

The affected capture instance, if known.

databaseName string

The database name, if known.

Returns

CdcPositionResetEventArgs

A populated CdcPositionResetEventArgs instance.

GetReasonCode(SqlException?)

Determines the appropriate reason code from a SQL exception.

public static string GetReasonCode(SqlException? exception)

Parameters

exception SqlException

The SQL exception to analyze.

Returns

string

The reason code string.

GetStalePositionErrorNumber(Exception?)

Extracts the SQL error number that indicates a stale position from the exception.

public static int? GetStalePositionErrorNumber(Exception? exception)

Parameters

exception Exception

The exception to analyze.

Returns

int?

The SQL Server error number if found; otherwise, null.

IsStalePositionException(Exception?)

Determines whether the specified exception indicates a stale CDC position.

public static bool IsStalePositionException(Exception? exception)

Parameters

exception Exception

The exception to analyze.

Returns

bool

true if the exception indicates a stale position; otherwise, false.