util/X86LINUX64/share/man/mann/tdbc_statement.n

   1 '\"
   2 '\" tdbc_statement.n --
   3 '\"
   4 '\" Copyright (c) 2008 by Kevin B. Kenny.
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution of
   7 '\" this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 .TH "tdbc::statement" n 8.6 Tcl "Tcl Database Connectivity"
   9 '\" .so man.macros
  10 '\" IGNORE
  11 .if t .wh -1.3i ^B
  12 .nr ^l \n(.l
  13 .ad b
  14 '\"     # BS - start boxed text
  15 '\"     # ^y = starting y location
  16 '\"     # ^b = 1
  17 .de BS
  18 .br
  19 .mk ^y
  20 .nr ^b 1u
  21 .if n .nf
  22 .if n .ti 0
  23 .if n \l'\\n(.lu\(ul'
  24 .if n .fi
  25 ..
  26 '\"     # BE - end boxed text (draw box now)
  27 .de BE
  28 .nf
  29 .ti 0
  30 .mk ^t
  31 .ie n \l'\\n(^lu\(ul'
  32 .el \{\
  33 '\"     Draw four-sided box normally, but don't draw top of
  34 '\"     box if the box started on an earlier page.
  35 .ie !\\n(^b-1 \{\
  36 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  37 .\}
  38 .el \}\
  39 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  40 .\}
  41 .\}
  42 .fi
  43 .br
  44 .nr ^b 0
  45 ..
  46 '\"     # CS - begin code excerpt
  47 .de CS
  48 .RS
  49 .nf
  50 .ta .25i .5i .75i 1i
  51 ..
  52 '\"     # CE - end code excerpt
  53 .de CE
  54 .fi
  55 .RE
  56 ..
  57 '\" END IGNORE
  58 .BS
  59 .SH "NAME"
  60 tdbc::statement \- TDBC statement object
  61 .SH "SYNOPSIS"
  62 .nf
  63 package require \fBtdbc 1.0\fR
  64 package require \fBtdbc::\fR\fIdriver version\fR
  65
  66 \fBtdbc::\fR\fIdriver\fR\fB::connection create \fR\fIdb\fR \fI?\-option value\fR...?
  67
  68 \fBset\fR \fIstmt\fR \fB[\fR\fIdb\fR \fBprepare\fR \fIsql-code\fR\fB]\fR
  69 \fBset\fR \fIstmt\fR \fB[\fR\fIdb\fR \fBpreparecall\fR \fIcall\fR\fB]\fR
  70
  71 \fI$stmt\fR \fBparams\fR
  72 \fI$stmt\fR \fBparamtype\fR ?\fIdirection\fR? \fItype\fR ?\fIprecision\fR? ?\fIscale\fR?
  73 \fI$stmt\fR \fBexecute\fR ?\fIdict\fR?
  74 \fI$stmt\fR \fBresultsets\fR
  75 .fi
  76 .ad l
  77 .in 14
  78 .ti 7
  79 \fI$stmt\fR \fBallrows\fR ?\fB-as lists|dicts\fR? ?\fB-columnsvariable\fR \fIname\fR? ?\fB--\fR? ?\fIdict\fR
  80 .br
  81 .ti 7
  82 \fI$stmt\fR \fBforeach\fR ?\fB-as lists|dicts\fR? ?\fB-columnsvariable\fR \fIname\fR? ?\fB--\fR? \fIvarName\fR ?\fIdict\fR? \fIscript\fR
  83 .br
  84 .ti 7
  85 \fI$stmt\fR \fBclose\fR
  86 .ad b
  87 .BE
  88 .SH "DESCRIPTION"
  89 .PP
  90 Every database driver for TDBC (Tcl DataBase Connectivity) implements
  91 a \fIstatement\fR object that represents a SQL statement in a
  92 database. Instances of this object are created by executing the
  93 \fBprepare\fR or \fBpreparecall\fR object command on a database
  94 connection.
  95 .PP
  96 The \fBprepare\fR object command against the connection
  97 accepts arbitrary SQL code to be
  98 executed against the database. The SQL code may contain \fIbound
  99 variables\fR, which are strings of alphanumeric characters or
 100 underscores (the first character of the string may not be numeric),
 101 prefixed with a colon (\fB:\fR). If a bound variable appears in the
 102 SQL statement, and is not in a string set off by single or double
 103 quotes, nor in a comment introduced by \fB--\fR, it becomes a value
 104 that is substituted when the statement is executed. A bound variable
 105 becomes a single value (string or numeric) in the resulting
 106 statement. \fIDrivers are responsible for ensuring that the mechanism
 107 for binding variables prevents SQL injection.\fR
 108 .PP
 109 The \fBpreparecall\fR object command against the connection accepts a
 110 stylized statement in the form:
 111 .PP
 112 .CS
 113 \fIprocname\fR \fB(\fR?\fB:\fR\fIvarname\fR? ?\fB,:\fR\fIvarname\fR...?\fB)\fR
 114 .CE
 115 .PP
 116 or
 117 .PP
 118 .CS
 119 \fIvarname\fR \fB=\fR \fIprocname\fR \fB(\fR?\fB:\fR\fIvarname\fR? ?\fB,:\fR\fIvarname\fR...?\fB)\fR
 120 .CE
 121 .PP
 122 This statement represents a call to a stored procedure \fIprocname\fR in the
 123 database. The variable name to the left of the equal sign (if
 124 present), and all variable names that are parameters inside
 125 parentheses, become bound variables.
 126 .PP
 127 The \fBparams\fR method against a statement object enumerates the
 128 bound variables that appear in the statement. The result returned from
 129 the \fBparams\fR method is a dictionary whose keys are the names of
 130 bound variables (listed in the order in which the variables first
 131 appear in the statement), and whose values are dictionaries. The
 132 subdictionaries include at least the following keys (database drivers
 133 may add additional keys that are not in this list).
 134 .IP \fBdirection\fR
 135 Contains one of the keywords, \fBin\fR, \fBout\fR or \fBinout\fR
 136 according to whether the variable is an input to or output from the
 137 statement. Only stored procedure calls will have \fBout\fR or
 138 \fBinout\fR parameters.
 139 .IP \fBtype\fR
 140 Contains the data type of the column, and will generally be chosen
 141 from the set,
 142 \fBbigint\fR, \fBbinary\fR, \fBbit\fR, \fBchar\fR, \fBdate\fR,
 143 \fBdecimal\fR, \fBdouble\fR, \fBfloat\fR, \fBinteger\fR,
 144 \fBlongvarbinary\fR, \fBlongvarchar\fR, \fBnumeric\fR, \fBreal\fR,
 145 \fBtime\fR, \fBtimestamp\fR, \fBsmallint\fR, \fBtinyint\fR,
 146 \fBvarbinary\fR, and \fBvarchar\fR. (If the variable has a type that
 147 cannot be represented as one of the above, \fBtype\fR will contain
 148 a driver-dependent description of the type.)
 149 .IP \fBprecision\fR
 150 Contains the precision of the column in bits, decimal digits, or the
 151 width in characters, according to the type.
 152 .IP \fBscale\fR
 153 Contains the scale of the column (the number of digits after the radix
 154 point), for types that support the concept.
 155 .IP \fBnullable\fR
 156 Contains 1 if the column can contain NULL values, and 0 otherwise.
 157 .PP
 158 The \fBparamtype\fR object command allows the script to specify the
 159 type and direction of parameter transmission of a variable in a
 160 statement. (Some databases provide no method to determine this
 161 information automatically and place the burden on the caller to do
 162 so.) The \fIdirection\fR, \fItype\fR, \fIprecision\fR, \fIscale\fR,
 163 and \fInullable\fR arguments have the same meaning as the
 164 corresponding dictionary values in the \fBparams\fR object command.
 165 .PP
 166 The \fBexecute\fR object command executes the statement. Prior to
 167 executing the statement, values are provided for the bound variables
 168 that appear in it.  If the \fIdict\fR parameter is supplied, it is
 169 searched for a key whose name matches the name of the bound
 170 variable. If the key is present, its value becomes the substituted
 171 variable. If not, the value of the substituted variable becomes a SQL
 172 NULL. If the \fIdict\fR parameter is \fInot\fR supplied, the
 173 \fBexecute\fR object command searches for a variable in the caller's
 174 scope whose name matches the name of the bound variable. If one is
 175 found, its value becomes the bound variable's value. If none is found,
 176 the bound variable is assigned a SQL NULL as its value.  Once
 177 substitution is finished, the resulting statement is executed. The
 178 return value is a result set object (see \fBtdbc::resultset\fR for
 179 details).
 180 .PP
 181 The \fBresultsets\fR method returns a list of all the result sets that
 182 have been returned by executing the statement and have not yet been
 183 closed.
 184 .PP
 185 The \fBallrows\fR object command executes the statement as with the
 186 \fBexecute\fR object command, accepting an
 187 optional \fIdict\fR parameter giving bind variables. After executing
 188 the statement,
 189 it uses the \fIallrows\fR object command on the result set (see
 190 \fBtdbc::resultset\fR) to construct a list of the results. Finally,
 191 the result set is closed. The return value is the list of
 192 results.
 193 .PP
 194 The \fBforeach\fR object command executes the statement as with the
 195 \fBexecute\fR object command, accepting an
 196 optional \fIdict\fR parameter giving bind variables. After executing
 197 the statement,
 198 it uses the \fIforeach\fR object command on the result set (see
 199 \fBtdbc::resultset\fR) to evaluate the given \fIscript\fR for each row of
 200 the results. Finally, the result set is closed, even
 201 if the given \fIscript\fR results in a \fBreturn\fR, an error, or
 202 an unusual return code.
 203 .PP
 204 The \fBclose\fR object command removes a statement and any result sets
 205 that it has created. All system resources associated with the objects
 206 are freed.
 207 .SH "EXAMPLES"
 208 The following code would look up a telephone number in a directory,
 209 assuming an appropriate SQL schema:
 210 .PP
 211 .CS
 212 package require tdbc::sqlite3
 213 tdbc::sqlite3::connection create db phonebook.sqlite3
 214 set statement [db prepare {
 215     select phone_num from directory
 216     where first_name = :firstname and last_name = :lastname
 217 }]
 218 set firstname Fred
 219 set lastname Flintstone
 220 $statement foreach row {
 221     puts [dict get $row phone_num]
 222 }
 223 $statement close
 224 db close
 225 .CE
 226 .SH "SEE ALSO"
 227 encoding(n), tdbc(n), tdbc::connection(n), tdbc::resultset(n), tdbc::tokenize(n)
 228 .SH "KEYWORDS"
 229 TDBC, SQL, database, connectivity, connection, resultset, statement,
 230 bound variable, stored procedure, call
 231 .SH "COPYRIGHT"
 232 Copyright (c) 2008 by Kevin B. Kenny.
 233 '\" Local Variables:
 234 '\" mode: nroff
 235 '\" End:
 236 '\"