tdbc::resultset(n) Tcl Database Connectivity tdbc::resultset(n)______________________________________________________________________________NAME
tdbc::resultset - TDBC result set object
SYNOPSIS
package require tdbc 1.0
package require tdbc::driver version
tdbc::driver::connection create db ?-option value...?
set stmt [db prepare sql-code]
set resultset [$stmt execute ?args...?
$resultset columns
$resultset rowcount
$resultset nextrow ?-as lists|dicts? ?--? varname
$resultset nextlist varname
$resultset nextdict varname
$resultset allrows ?-as lists|dicts? ?-columnsvariable name? ?--?
$resultset foreach ?-as lists|dicts? ?-columnsvariable name? ?--? var‐
name script
$resultset close
_DESCRIPTION
Every database driver for TDBC (Tcl DataBase Connectivity) implements a
result set object that represents a the results returned from executing
SQL statement in a database. Instances of this object are created by
executing the execute object command on a statement object.
The columns obect command returns a list of the names of the columns in
the result set. The columns will appear in the same order as they
appeared in the SQL statement that performed the database query. If the
SQL statement does not return a set of columns (for instance, if it is
an INSERT, UPDATE, or DELETE statement), the columns command will
return an empty list.
The rowcount object command returns the number of rows in the database
that were affected by the execution of an INSERT, UPDATE or DELETE
statement. For a SELECT statement, the row count is unspecified.
The nextlist object command sets the variable given by varname in the
caller's scope to the next row of the results, expressed as a list of
column values. NULL values are replaced by empty strings. The columns
of the result row appear in the same order in which they appeared on
the SELECT statement. The return of nextlist is 1 if the operation suc‐
ceeded, and 0 if the end of the result set was reached.
The nextdict object command sets the variable given by varname in the
caller's scope to the next row of the results, expressed as a dictio‐
nary. The dictionary's keys are column names, and the values are the
values of those columns in the row. If a column's value in the row is
NULL, its key is omitted from the dictionary. The keys appear in the
dictionary in the same order in which the columns appeared on the
SELECT statement. The return of nextdict is 1 if the operation suc‐
ceeded, and 0 if the end of the result set was reached.
The nextrow object command is precisely equivalent to the nextdict or
nextlist object command, depending on whether -as dicts (the default)
or -as lists is specified.
The allrows object command sets the variable designated by the
-columnsvariable option (if present) to the result of the columns
object command. It then executes the nextrow object command repeatedly
until the end of the result set is reached. The resulting rows are
assembled into a Tcl list and become the return value of the allrows
command.
The foreach object command sets the variable designated by the
-columnsvariable option (if present) to the result of the columns
object command. It then executes the nextrow object command repeatedly
until the end of the result set is reached, storing the successive rows
in the variable designated by varName. For each row, it executes the
given script. If the script terminates with an error, the error is
reported by the foreach command, and iteration stops. If the script
performs a break operation, the iteration terminates prematurely. If
the script performs a continue operation, the iteration recommences
with the next row. If the script performs a return, results are the
same as if a script outside the control of foreach had returned. Any
other unusual return code terminates the iteration and is reported from
the foreach.
The close object command deletes the result set and frees any associ‐
ated system resources.
SEE ALSOencoding(n), tdbc(n), tdbc_connection(n), tdbc_statement(n), tdbc_tok‐
enize(n)KEYWORDS
TDBC, SQL, database, connectivity, connection, resultset, statement,
bound variable, stored procedure, call
COPYRIGHT
Copyright (c) 2008 by Kevin B. Kenny.
Tcl 8.6 tdbc::resultset(n)
