## Tcl8.6.17/Tk8.6.17 Documentation > TDBC Package Commands, version 1.1.12 > tdbc_resultset

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

### 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 nextresults
$resultset allrows ?-as lists|dicts? ?-columnsvariable name? ?--?
$resultset foreach ?-as lists|dicts? ?-columnsvariable name? ?--? varname script
$resultset close

### DESCRIPTION

全てのTDBC (Tcl DataBase Connectivity) の為の基礎データ駆動譜は result set 対象を実装する､それは､基礎データ内でSQL 命令文を実行した結果から返される結果を具現する｡この対象の即値は命令文対象上の execute 対象命令の実行により生成される｡　　　　　　 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.

columns 対象命令は､結果の組の中の欄の名前のリストを返す｡その欄は基礎データの問合せを実行した SQL 命令文に現れた順序と同じ順序で現れる｡もし SQL 命令文が欄の組を返さない場合(譬えば､ INSERT 命令文や UPDATE 命令文や DELETE 命令文の場合)､columns 命令文は空リストを返す｡ 　　　　　　 The columns object 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.

rowcount 対象命令は INSERT 命令文や UPDATE 命令文や DELETE 命令文の実行により影響を受けた基礎データ内の行の個数を返す｡SELECT 命令文については､行の数は指定されない｡　　　　　　 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.

nextlist 対象命令は呼出し側の有効範囲内に varname として与えられた変数を､結果の次の行に､欄の値のリストとして表現して設定する｡ NULL 値は空文字列に置換される｡結果の行の欄は､ SELECT 命令文上に現れたのと同じ順序で現れる｡もし操作が成功すると､nextlist の返りは 1 であり､もし結果の組の末尾に到達すると 0 である｡　　　　　　 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 succeeded, and 0 if the end of the result set was reached.

nextdict 対象命令は呼出し側の有効範囲内に varname として与えられた変数を､結果の次の行に､欄の値の辞書として表現して設定する｡その辞書の検索用語は欄の名前であり､値は行内のその欄の値である｡行内の欄の値が NULL の場合､その検索用語は辞書から省略される｡辞書内の検索用語は､ SELECT 命令文上に現れたのと同じ順序で現れる｡もし操作が成功すると､nextdict の返りは 1 であり､もし結果の組の末尾に到達すると 0 である｡ 　　 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 dictionary. 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 succeeded, and 0 if the end of the result set was reached.

nextrow 対象命令は､-as dicts (無為設定) か -as lists のどちらが指定されているかによって､正確に nextdict 対象命令か nextlist 対象命令 のどちらかと等価である｡ 　　　　　　 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.

ある基礎データは一つの命令文が多重の結果の組を返す概念を運営している｡nextresults 対象命令は､次の結果の組に進捗する為に､典型的には nextlist 又は nextdict 対象命令が 0 を返した後に､実行される(訳注 of→or)｡それは､処理すべき別の結果が在る場合､1 を返し､今処理した結果の組が最後であれば 0 を返す｡nextresults 呼出しの後に返り値 1 を得ると､呼出し側は､次の結果の組の欄の記述を得る為にもう一度 columns を呼出しても良い､その次に､次の結果の行を処理する為に nextdict か nextlist を呼出しに帰る｡nextresults が 0 を返した後に､columns や nextdict や nextlist や nextrow を呼ぶことは不都合になる｡ 　　　　　　 Some databases support the idea of a single statement that returns multiple sets of results. The nextresults object command is executed, typically after the nextlist of nextdict object command has returned 0, to advance to the next result set. It returns 1 if there is another result set to process, and 0 if the result set just processed was the last. After calling nextresults and getting the return value of 1, the caller may once again call columns to get the column descriptions of the next result set, and then return to calling nextdict or nextlist to process the rows of the next result set. It is an error to call columns, nextdict, nextlist or nextrow after nextresults has returned 0.

allrows 対象命令は､-columnsvariable 指定(がある場合)によって指定された変数に､columns 対象命令の結果を設定する｡次に結果の組が末尾に達するまで nextrow 対象命令を繰返し実行する｡もし nextresults が非零値を返す場合､それは､更なる結果が利用できる限り､上述の二つの段階(columns に繰返し nextrow 呼出しが続く)を実行する｡ nextrow によって返された行は Tcl リストの中に組入れられ､allrows 命令の返り値になる; columns から返された最後の値は応用譜が -columnsvariable 内に見ることになるものである｡ 　　　　　　 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. If nextresults returns a nonzero value, it executes the above two steps (columns followed by iterated nextrow calls) as long as further results are available. The rows returned by nextrow are assembled into a Tcl list and become the return value of the allrows command; the last value returned from columns is what the application will see in -columnsvariable.

foreach 対象命令は､-columnsvariable 指定(がある場合)によって指定された変数に､columns 対象命令の結果を設定する｡次に結果の組が末尾に達するまで nextrow 対象命令を繰返し実行して varName によって指定された変数内に連続した行を保存する｡それぞれの行の為に､与えられた記述譜 script を実行する｡もし､記述譜が不都合で終了すると､不都合は foreach 命令によって報告され､繰返しは停止する｡もし記述譜が break 操作を遂行すると､繰返しは早期に終る｡もし記述譜が continue 操作を遂行すると､繰り返しは次の行から遣り直す｡もし記述譜が return 操作を遂行すると､結果は foreach の制御の外の記述譜が返ったのと同じである｡それ以外の通常でない返り符号は繰返しを終らせ､foreach から報告される｡ 　　　　　　　 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.

一たび nextrow が 0 を返すと､foreach 対象命令は､nextresults を使用して次の結果の組に進行しようと試みる｡もし､nextresults が B>1 を返すと､更なる結果の組が残る限り上述の段階(記述譜の実行を伴う columns と nextrow)が繰返される｡ 記述譜 script は常に､-columnsvariable によって指定された変数内の､現在の結果の組の欄の正しい記述を見ている｡呼出しの終わりに､ -columnsvariable によって指定された変数は最後の結果の組の欄の記述を有する｡(訳註 byt →by) 　　　　　　　　　 Once nextrow returns 0, the foreach object command tries to advance to the next result set using nextresults. If nextresults returns 1, the above steps (columns and nextrow, with script invocation) are repeated as long as more result sets remain. The script will always see the correct description of the columns of the current result set in the variable designated byt -columnsvariable. At the end of the call, the variable designated by -columnsvariable will have the description of the columns of the last result set.

close 対象命令は､結果の組を削除しどの結合された系の原資も解放する｡　　　　　　　 The close object command deletes the result set and frees any associated system resources.

### SEE ALSO

encoding, tdbc, tdbc::connection, tdbc::statement, tdbc::tokenize

### KEYWORDS

TDBC, SQL, database, connectivity, connection, resultset, statement, bound variable, stored procedure, call

### COPYRIGHT

Copyright (c) 2008 by Kevin B. Kenny.
Copyright © 2008 by Kevin B. Kenny.