::nsmcp::Object ::nsmcp::Object dict getdef ::nx::Object ::nx::Object ::nsmcp::Object->::nx::Object ::nsmcp::DatabaseSession ::nsmcp::DatabaseSession batchCapabilities batchInsert changes close destroy execute executeDml inTransaction init scalar statements transaction ::nsmcp::DatabaseSession->::nsmcp::Object

Class ::nsmcp::DatabaseSession

::nsmcp::DatabaseSession[i] create ... \
           [ -handle:required handle:required ] \
           [ -inTransaction inTransaction ] \
           [ -scripts scripts ]
Defined in /usr/local/ns/tcl/nsmcp/database.tcl

Class Relations

  • class: ::nx::Class[i]
  • superclass: ::nsmcp::Object[i]
::nx::Class create ::nsmcp::DatabaseSession \
     -superclass ::nsmcp::Object

Methods (to be applied on instances)

  • batchCapabilities (scripted, public)

     <instance of nsmcp::DatabaseSession[i]> batchCapabilities

    Describe batch insertion support on the owned handle. Ask core nsdb for this driver's current batch capabilities.

    Returns:
    The batch-capability dictionary.

    Testcases:
    No testcase defined.
    return [ns_db batchinfo -handle ${:handle}]

  • batchInsert (scripted, public)

     <instance of nsmcp::DatabaseSession[i]> batchInsert \
    [ -mapping mapping ] [ -schema schema ] table batch

    Insert a supplied prepared batch using core nsdb's batch API. Pass optional column mapping and schema metadata to the owned database handle.

    Switches:
    -mapping (optional)
    Optional core batch column mapping.
    -schema (optional)
    Optional prepared-row schema.
    Parameters:
    table (required)
    Target table identifier accepted by core batch insertion.
    batch (required)
    Prepared batch object or rows accepted by core nsdb.
    Returns:
    The batch insertion result returned by ns_db.

    Testcases:
    No testcase defined.
    set options [list -table $table]
if {$mapping ne {}} {
    lappend options -columns $mapping
}
if {$schema ne {}} {
    lappend options -schema $schema
}
return [ns_db batchinsert ${:handle} {*}$options $batch]

  • changes (scripted, public)

     <instance of nsmcp::DatabaseSession[i]> changes

    Read SQLite's affected-row count for the most recent statement. Query changes() on the owned handle without acquiring another session.

    Returns:
    The most recent SQLite change count.

    Testcases:
    No testcase defined.
    return [:scalar {SELECT changes()}]

  • close (scripted, public)

     <instance of nsmcp::DatabaseSession[i]> close

    Release this session and its checked-out database handle. Destroy the adapter so its destructor performs the connection cleanup.

    Returns:
    The object destruction result.

    Testcases:
    No testcase defined.
    :destroy

  • execute (scripted, public)

     <instance of nsmcp::DatabaseSession[i]> execute \
    [ -arrayName arrayName ] [ -script script ] sql

    Execute trusted SQL statements with bindings from the caller's scope. Materialize ns_set rows directly as alternating key/value lists, or run the row callback through the supplied caller array; always flush result sets.

    Switches:
    -arrayName (optional)
    Optional caller-array name populated for each fetched row.
    -script (optional)
    Tcl script executed in the documented caller or callback context.
    Parameters:
    sql (required)
    Trusted SQL text; current values are resolved in the caller's scope.
    Returns:
    The collected row lists, or an empty list when rows are consumed through a callback.

    Testcases:
    No testcase defined.
    set rows {}
foreach statement [:statements $sql] {
    # Core resolves current caller values and rejects missing names.
    set kind [uplevel 1 [list ns_db exec ${:handle} -bindvars -- $statement]]
    set command [string toupper [lindex [split [string trim $statement]] 0]]
    if {$command eq "BEGIN"} {
        set :inTransaction true
    }
    if {$command in {COMMIT ROLLBACK END}} {
        set :inTransaction false
    }
    if {$kind ne "NS_ROWS"} {
        continue
    }
    set row [ns_db bindrow ${:handle}]
    try {
        # Column names do not change between rows. Callback metadata
        # retains their original order, including duplicate names.
        if {$arrayName ne ""} {
            set keys [ns_set keys $row]
        }
        while {[ns_db getrow ${:handle} $row]} {
            set record [ns_set array $row]
            if {$arrayName eq ""} {
                lappend rows $record
            } else {
                upvar 1 $arrayName target
                array unset target
                array set target $record
                set target(*) $keys
                set code [catch {
                    uplevel 1 $script
                } value options]
                if {$code==3} {
                    break
                }
                if {$code==4} {
                    continue
                }
                if {$code} {
                    return -options $options $value
                }
            }
        }
    } finally {
        ns_db flush ${:handle}
        ns_set free $row
    }
}
return $rows

  • executeDml (scripted, public)

     <instance of nsmcp::DatabaseSession[i]> executeDml \
    [ -bindtypes bindtypes ] statement

    Execute one statement and require a DML result. Execute serialized SQL as supplied; when bindtypes is provided, resolve caller variables through core binding with that explicit type metadata.

    Switches:
    -bindtypes (optional)
    Optional dictionary describing scalar, list, rows or binary bindings.
    Parameters:
    statement (required)
    One trusted SQL statement, with optional named value bindings.
    Returns:
    An empty result on success; row-returning statements raise an error.

    Testcases:
    No testcase defined.
    if {$bindtypes eq {}} {
    set kind [ns_db exec ${:handle} $statement]
} else {
    set kind [uplevel 1 [list ns_db exec ${:handle} -bindvars -bindtypes $bindtypes -- $statement]]
}
if {$kind eq "NS_ROWS"} {
    ns_db flush ${:handle}
    error "Expected a non-row-returning serialized DML statement"
}

  • inTransaction (scripted, public)

     <instance of nsmcp::DatabaseSession[i]> inTransaction

    Report the transaction state tracked by this session. The flag follows transaction statements executed through this adapter.

    Returns:
    The current transaction flag.

    Testcases:
    No testcase defined.
    return ${:inTransaction}

  • scalar (scripted, public)

     <instance of nsmcp::DatabaseSession[i]> scalar sql

    Execute a query and return its first value. Reuse execute in the caller's scope, retaining its current-variable binding behavior.

    Parameters:
    sql (required)
    Trusted SQL text; current values are resolved in the caller's scope.
    Returns:
    The first column of the first row, or an empty result when no row is returned.

    Testcases:
    No testcase defined.
    set rows [uplevel 1 [list [nsf::current object] execute $sql]]
if {$rows eq ""} {
    return {}
}
return [lindex [lindex $rows 0] 1]

  • transaction (scripted, public)

     <instance of nsmcp::DatabaseSession[i]> transaction script

    Execute a caller script inside an immediate SQLite transaction. Commit on normal completion and roll back if the script or commit raises an error.

    Parameters:
    script (required)
    Tcl script executed in the documented caller or callback context.
    Returns:
    The caller script's result on successful commit.

    Testcases:
    No testcase defined.
    :execute {BEGIN IMMEDIATE}
try {
    set value [uplevel 1 $script]
    :execute COMMIT
    return $value
} on error {message options} {
    catch {
        :execute ROLLBACK
    }
    return -options $options $message
}