ODBCErrorChain¶

Accumulates error frames from ODBC operations.

The error chain maintains a configurable history of error events, allowing inspection of what operations failed and why. It supports:

Maximum frame limit with oldest-first eviction
Optional auto-clear on prepare/finish operations
Optional logging of successful operations for tracing

Configuration¶

stmt.configure_error_chain(
  max_frames = 50,
  auto_clear = true,
  log_success = false
)

Usage¶

// Access the most recent error
match stmt.last_error()
| let err: ODBCErrorFrame val =>
  env.err.print(err.string())
end

// Iterate over all errors
for err in stmt.error_chain().values() do
  env.err.print(err.operation + ": " + err.message())
end

// Print formatted chain
env.err.print(stmt.error_chain().string())

class ref ODBCErrorChain

Constructors¶

create¶

[Source]

Create a new error chain with default settings.

new ref create()
: ODBCErrorChain ref^

Returns¶

ODBCErrorChain ref^

Public Functions¶

push¶

[Source]

Add a frame to the chain, evicting the oldest if at capacity.

fun ref push(
  frame: ODBCErrorFrame val)
: None val

Clear all stored frames. Sequence counter is preserved.

fun ref clear()
: None val

Returns¶

None val

size¶

[Source]

Number of currently stored frames.

fun box size()
: USize val

Returns¶

USize val

values¶

[Source]

Iterate over frames from oldest to newest.

fun box values()
: ArrayValues[ODBCErrorFrame val, this->Array[ODBCErrorFrame val] ref] ref^

Returns¶

ArrayValues[ODBCErrorFrame val, this->Array[ODBCErrorFrame val] ref] ref^

last¶

[Source]

Get the most recent error frame, or None if empty.

fun box last()
: (ODBCErrorFrame val | None val)

Returns¶

(ODBCErrorFrame val | None val)

first¶

[Source]

Get the oldest error frame, or None if empty.

fun box first()
: (ODBCErrorFrame val | None val)

Returns¶

(ODBCErrorFrame val | None val)

apply¶

[Source]

Get frame by index. Throws if out of bounds.

fun box apply(
  i: USize val)
: ODBCErrorFrame val ?

Parameters¶

i: USize val

Returns¶

ODBCErrorFrame val ?

string¶

[Source]

Format the entire chain for display.

Output format:

Error chain (2 errors):
  1. [stmt] prepare at main.pony:41 - OK
  2. [stmt] execute at main.pony:42 - 42S02: Table 'nonexistent' doesn't exist

fun box string()
: String val

Returns¶

String val

next_sequence¶

[Source]

Get and increment the sequence counter.

fun ref next_sequence()
: USize val

Returns¶

USize val

current_sequence¶

[Source]

Get the current sequence counter without incrementing.

fun box current_sequence()
: USize val

Returns¶

USize val

set_max_frames¶

[Source]

Configure maximum number of stored frames. When reduced, excess frames are evicted oldest-first.

fun ref set_max_frames(
  n: USize val)
: None val

Parameters¶

n: USize val

Returns¶

None val

max_frames¶

[Source]

Get the current maximum frames setting.

fun box max_frames()
: USize val

Returns¶

USize val

set_auto_clear¶

[Source]

Configure auto-clear behavior. When true, the chain is cleared on prepare()/finish() calls.

fun ref set_auto_clear(
  v: Bool val)
: None val

Parameters¶

v: Bool val

Returns¶

None val

auto_clear¶

[Source]

Get the current auto-clear setting.

fun box auto_clear()
: Bool val

Returns¶

Bool val

set_log_success¶

[Source]

Configure success logging. When true, successful operations are also recorded in the chain.

fun ref set_log_success(
  v: Bool val)
: None val

Parameters¶

v: Bool val

Returns¶

None val

log_success¶

[Source]

Get the current log_success setting.

fun box log_success()
: Bool val

Returns¶

Bool val

errors_only¶

[Source]

Return only error frames (not success frames).

fun box errors_only()
: Array[ODBCErrorFrame val] val

Returns¶

Array[ODBCErrorFrame val] val