## Tcl9.0.3/Tk9.0.3 Documentation > TDBC Package Commands, version 1.1.13 > tdbc_statement

### 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::statement — TDBC statement object
  SYNOPSIS
  説明 DESCRIPTION
    方向direction
    型type
    精度precision
    桁scale
    null許容nullable
  用例 EXAMPLES
  SEE ALSO
  KEYWORDS
  COPYRIGHT

### NAME

tdbc::statement — TDBC statement 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 stmt [db preparecall call]
$stmt params
$stmt paramtype ?direction? type ?precision? ?scale?
$stmt execute ?dict?
$stmt resultsets
$stmt allrows ?-as lists|dicts? ?-columnsvariable name? ?--? ?dict
$stmt foreach ?-as lists|dicts? ?-columnsvariable name? ?--? varName ?dict? script
$stmt close

### 説明 DESCRIPTION

全ての TDBC (Tcl DataBase Connectivity) の為の基礎データ駆動譜は､基礎データ内の SQL 命令文を代表する 命令文 statement 対象を実装する｡この対象の即値は､基礎データ接続上の prepare か preparecall 対象命令の実行によって生成される｡　　　　　 Every database driver for TDBC (Tcl DataBase Connectivity) implements a statement object that represents a SQL statement in a database. Instances of this object are created by executing the prepare or preparecall object command on a database connection.

接続に対する prepare 対象命令は､基礎データに対して実行される任意の SQL 符号命令を受入れる｡ SQL 符号命令は､束縛変数 を含んでもよい､それは､コロン(:)が先頭に付いて､英数字か下線文字の文字列(文字列の最初の文字は数字であってならない)である｡ もし束縛変数が SQL 命令文内に現れ､且つ､一重か二重引用記号で区切られていなく､且つ.--により導かれた注釈内ではない場合､それは､命令文が実行された時に､置換される値になる｡ 束縛変数は､結果の命令文内の一つの値(文字列か数値)になる｡ 束縛変数がSQL 挿入を阻止する為の仕組みが確実であることは駆動譜の責務である｡　　　　　　 The prepare object command against the connection accepts arbitrary SQL code to be executed against the database. The SQL code may contain bound variables, which are strings of alphanumeric characters or underscores (the first character of the string may not be numeric), prefixed with a colon (:). If a bound variable appears in the SQL statement, and is not in a string set off by single or double quotes, nor in a comment introduced by --, it becomes a value that is substituted when the statement is executed. A bound variable becomes a single value (string or numeric) in the resulting statement. Drivers are responsible for ensuring that the mechanism for binding variables prevents SQL injection.

接続に対する preparecall 対象命令は､この形式で様式化された命令文を受入れる:　　　　　　　 The preparecall object command against the connection accepts a stylized statement in the form:

    procname (?:varname? ?,:varname...?)

又は　　　　　 or

    varname = procname (?:varname? ?,:varname...?)

この命令文は基礎データ内の保存された手続函数 procname の呼出しを具現する｡ 等号の左にある変数の名前(もしあれば)と､括弧の中にある全ての媒介変数の変数の名前は､束縛変数になる｡　　　　　　 This statement represents a call to a stored procedure procname in the database. The variable name to the left of the equal sign (if present), and all variable names that are parameters inside parentheses, become bound variables.

命令文対象に対する params 手段は､命令文内に現れる束縛変数を数え上げる｡params 手段から返される結果は辞書であり､その検索用語は束縛変数の名前である(変数が最初に命令文内に現れた順序で列挙され)､又その値は辞書である｡ 副辞書は少なくとも次の検索用語を含む(基礎データ駆動譜はこのリストにはない追加の検索用語を加えるかもしれない)｡　　　　　　 The params method against a statement object enumerates the bound variables that appear in the statement. The result returned from the params method is a dictionary whose keys are the names of bound variables (listed in the order in which the variables first appear in the statement), and whose values are dictionaries. The subdictionaries include at least the following keys (database drivers may add additional keys that are not in this list).

方向direction
  変数が､命令文に入力されるか､命令文から出力されるかに従って用語 in か out か inout の内の一つを含む｡ 保存される手続函数呼出しのみが out か inout 媒介変数を有する｡　　　　　　 Contains one of the keywords, in, out or inout according to whether the variable is an input to or output from the statement. Only stored procedure calls will have out or inout parameters.

型type
  欄のデータの型を含み､通常次の組から選択される､bigint, binary, bit, char, date, decimal, double, float, integer, longvarbinary, longvarchar, numeric, real, time, timestamp, smallint, tinyint, varbinary, and varchar｡ (もし､変数が上述の一つで表されない型を有する場合､型type は､駆動譜依存の型記述を含む｡)　　　　　　 Contains the data type of the column, and will generally be chosen from the set, bigint, binary, bit, char, date, decimal, double, float, integer, longvarbinary, longvarchar, numeric, real, time, timestamp, smallint, tinyint, varbinary, and varchar. (If the variable has a type that cannot be represented as one of the above, type will contain a driver-dependent description of the type.)

精度precision
  欄の精度を､型に従って､ビット､十進数､文字の巾で含む｡　　　　　　 Contains the precision of the column in bits, decimal digits, or the width in characters, according to the type.

桁scale
  欄の桁を含む､その概念を運営している型のみ(少数点の位置の後の十進数字の個数)｡　　　　　　 Contains the scale of the column (the number of digits after the radix point), for types that support the concept.

null許容nullable
  もし欄が NULL 値を含むことができる場合は 1 を､そうでない場合は 0 を含む｡　　　　　 Contains 1 if the column can contain NULL values, and 0 otherwise.

paramtype 対象命令は､記述譜に､命令文内の変数の媒介変数伝達の､型と方向を指定することを許容する(この情報を自動的に決定する手段を提供せず､呼出し者にそれをするよう負担を強いる基礎データもある)｡ 方向と型と精度と桁と null許容の引数は params対象命令内の対応する辞書値と同じ意味を有する｡　　　　　　　 The paramtype object command allows the script to specify the type and direction of parameter transmission of a variable in a statement. (Some databases provide no method to determine this information automatically and place the burden on the caller to do so.) The direction, type, precision, scale, and nullable arguments have the same meaning as the corresponding dictionary values in the params object command.

execute 対象命令は命令文を実行する｡ 命令文の実行に先立って､その中に現れる束縛変数の為に値が与えられる｡ もし dict 媒介変数が与えられると､それは､その名前が束縛変数の名前に合致する検索用語が捜される｡ もし検索用語が存在すると､その値は置換された変数になる｡ 存在しない場合､置換された変数の値は SQL NULL になる｡ もし dict 媒介変数が供給されない場合､execute 対象命令は､その名前が束縛変数の名前に合致する変数を呼出し者の有効範囲内で捜索する｡ もし一つ見付ると､その値は束縛変数の値になる｡ 見付らない場合､束縛変数はその値として SQL NULL が代入される｡ 一たび置換が終了すると､結果の命令文が実行される｡ 返り値は､結果の組の対象である(詳細は tdbc::resultset を参照されたい)｡　　　　　　　 The execute object command executes the statement. Prior to executing the statement, values are provided for the bound variables that appear in it. If the dict parameter is supplied, it is searched for a key whose name matches the name of the bound variable. If the key is present, its value becomes the substituted variable. If not, the value of the substituted variable becomes a SQL NULL. If the dict parameter is not supplied, the execute object command searches for a variable in the caller's scope whose name matches the name of the bound variable. If one is found, its value becomes the bound variable's value. If none is found, the bound variable is assigned a SQL NULL as its value. Once substitution is finished, the resulting statement is executed. The return value is a result set object (see tdbc::resultset for details).

resultsets 手段は､その命令の実行により返され､未だ閉じられていない全ての結果の組のリストを返す｡　　　　　　 　 The resultsets method returns a list of all the result sets that have been returned by executing the statement and have not yet been closed.

allrows 対象命令は､束縛している変数を与えている追加指示のdict媒介変数を受入れて､execute 対象命令のように､命令文を実行する｡ 命令文を実行した後､結果の組の上で､結果のリストを組上げる為に allrows 対象命令を使う(詳細は tdbc::resultset を参照されたい)｡ 最後に､結果の組が閉じられる｡ 結果の値は結果のリストである｡　　　　　　 The allrows object command executes the statement as with the execute object command, accepting an optional dict parameter giving bind variables. After executing the statement, it uses the allrows object command on the result set (see tdbc::resultset) to construct a list of the results. Finally, the result set is closed. The return value is the list of results.

foreach 対象命令は ､束縛している変数を与えている指示項目の dict 媒介変数を受入れて､execute 対象命令のように､命令文を実行する｡ 命令文を実行した後､それは､結果の組の上で､それぞれの結果の行に対して(詳細は tdbc::resultset を参照されたい)与えられた記述譜を評価する為に foreach 対象命令を使う｡ 最後に､縦え与えられた記述譜が見返りに 不都合, 又は通常ではない返り符号を返しても結果の組は閉じられる｡　　　　　　　 The foreach object command executes the statement as with the execute object command, accepting an optional dict parameter giving bind variables. After executing the statement, it uses the foreach object command on the result set (see tdbc::resultset) to evaluate the given script for each row of the results. Finally, the result set is closed, even if the given script results in a return, an error, or an unusual return code.

close 対象命令は､命令文と､それによって生成されたどのようなものも削除する｡その対象に結合している系の原資は全て解放される｡ 　　　 The close object command removes a statement and any result sets that it has created. All system resources associated with the objects are freed.

### 用例 EXAMPLES

次の符号命令は､ディレクトリーから電話番号を捜す､それが､適切な SQL 図式であると仮定して: 　　　　　　 The following code would look up a telephone number in a directory, assuming an appropriate SQL schema:

    package require tdbc::sqlite3
    tdbc::sqlite3::connection create db phonebook.sqlite3
    set statement [db prepare {
        select phone_num from directory
        where first_name = :firstname and last_name = :lastname
    }]
    set firstname Fred
    set lastname Flintstone
    $statement foreach row {
        puts [dict get $row phone_num]
    }
    $statement close
    db close

### SEE ALSO

encoding, tdbc, tdbc::connection, tdbc::resultset, 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.