::nsmcp::Object ::nsmcp::Object dict getdef ::nx::Object ::nx::Object __default_accessor __default_method_call_protection __object_configureparameter __resolve_method_path contains copy delete object method delete object property delete object variable destroy_on_cleanup info consts info info info lookup parameters info lookup slots info lookup syntax info lookup variables info object method args info object method body info object method callprotection info object method debug info object method definition info object method definitionhandle info object method deprecated info object method exists info object method handle info object method origin info object method parameters info object method registrationhandle info object method returns info object method submethods info object method syntax info object method type info object slots info object variables info variable definition info variable name info variable parameter move object alias object forward object method object property object variable private protected public qn require namespace require object method require private object method require protected object method require public object method serialize ::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
}