doc/mysqltcl.html

   1 <! -- -*- tcl -*- mysqltcl manpage
   2    -->
   3 <html><head>
   4 <title>mysqltcl -  </title>
   5 </head>
   6 <! -- Generated from file 'mysqltcl.man' by tcllib/doctools with format 'html'
   7    -->
   8 <! -- CVS: $Id$ mysqltcl.n
   9    -->
  10
  11 <body>
  12 <h1> mysqltcl(n) 3.0  &quot;&quot;</h1>
  13 <h2><a name="name">NAME</a></h2>
  14 <p>
  15 <p> mysqltcl - MySQL server access commands for Tcl
  16 <! --    -- Copyright (c) 1994, 1995 Hakan Soderstrom and Tom Poindexter   -- Permission to use, copy, modify, distribute, and sell this software   -- and its documentation for any purpose is hereby granted without fee,   -- provided that the above copyright notice and this permission notice   -- appear in all copies of the software and related documentation.   --     -- THE SOFTWARE IS PROVIDED &quot;AS-IS&quot; AND WITHOUT WARRANTY OF ANY KIND,   -- EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY   -- WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.   --     -- IN NO EVENT SHALL HAKAN SODERSTROM OR SODERSTROM PROGRAMVARUVERKSTAD   -- AB BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL   -- DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS   -- OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY   -- OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN   -- CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.   --     -- $Id: mysqltcl.n,v 1.1.1.1 2002/02/15 18:21:17 artur Exp $   --    -- Updates by Tobias Ritzau 1998-03-18   -- Replaced all mysql by mysql   -- Updated the mysqlconnect documentation   --     -- 1998-07-06   -- Changed some mysql back to msql   -- Updaated the name and introduction   -- Updated the mysqlcol documentation   --    -- Copyright (c) 1998 Tobias Ritzau   --    -- Updates by Artur Trzewik 2002-11-31   -- for mysqltcl2.1 (mysql::query mysq::endquery)   --    -- Updates by Artur Trzewik 2002-11-31   -- for mysqltcl3.0   --
  17    -->
  18
  19
  20
  21
  22
  23 <h2><a name="table_of_contents">TABLE OF CONTENTS</a></h2>
  24 <p>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#table_of_contents">TABLE OF CONTENTS</a><br>
  25 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#synopsis">SYNOPSIS</a><br>
  26 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#description">DESCRIPTION</a><br>
  27 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#mysqltcl_commands">MYSQLTCL COMMANDS</a><br>
  28 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#status_information">STATUS INFORMATION</a><br>
  29 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#backward_compatibility">Backward compatibility</a><br>
  30 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#bugs_&_possible_misfeatures">BUGS &amp; POSSIBLE MISFEATURES</a><br>
  31 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#authors">AUTHORS</a><br>
  32 <h2><a name="synopsis">SYNOPSIS</a></h2>
  33 <p>
  34 package require <b>Tcl 8.4</b><br>
  35 package require <b>mysqltcl 3.0</b><br>
  36 <br><table border=1 width=100% cellspacing=0 cellpadding=0><tr            bgcolor=lightyellow><td bgcolor=lightyellow><table 0 width=100% cellspacing=0 cellpadding=0><tr valign=top ><td ><a href="#1"><b class='cmd'>::mysql::connect</b> ?<i class='arg'>option value</i>...?</a></td></tr>
  37 <tr valign=top ><td ><a href="#2"><b class='cmd'>::mysql::use</b> <i class='arg'>handle</i> <i class='arg'>database</i></a></td></tr>
  38 <tr valign=top ><td ><a href="#3"><b class='cmd'>::mysql::sel</b> <i class='arg'>handle</i> <i class='arg'>sql-statement</i> ?<i class='arg'>-list|-flatlist</i>?</a></td></tr>
  39 <tr valign=top ><td ><a href="#4"><b class='cmd'>::mysql::fetch</b> <i class='arg'>handle</i></a></td></tr>
  40 <tr valign=top ><td ><a href="#5"><b class='cmd'>::mysql::exec</b> <i class='arg'>handle</i> <i class='arg'>sql-statement</i></a></td></tr>
  41 <tr valign=top ><td ><a href="#6"><b class='cmd'>::mysql::query</b> <i class='arg'>handle</i> <i class='arg'>sql-select-statement</i></a></td></tr>
  42 <tr valign=top ><td ><a href="#7"><b class='cmd'>::mysql::endquery</b> <i class='arg'>query-handle</i></a></td></tr>
  43 <tr valign=top ><td ><a href="#8"><b class='cmd'>::mysql::map</b> <i class='arg'>handle</i> <i class='arg'>binding-list</i> <i class='arg'>script</i></a></td></tr>
  44 <tr valign=top ><td ><a href="#9"><b class='cmd'>::mysql::receive</b> <i class='arg'>handle</i> <i class='arg'>sql-statment</i> <i class='arg'>binding-list</i> <i class='arg'>script</i></a></td></tr>
  45 <tr valign=top ><td ><a href="#10"><b class='cmd'>::mysql::seek</b> <i class='arg'>handle</i> <i class='arg'>row-index</i></a></td></tr>
  46 <tr valign=top ><td ><a href="#11"><b class='cmd'>::mysql::col</b> <i class='arg'>handle</i> <i class='arg'>table-name</i> <i class='arg'>option</i></a></td></tr>
  47 <tr valign=top ><td ><a href="#12"><b class='cmd'>::mysql::col</b> <i class='arg'>handle</i> <i class='arg'>table-name</i> <i class='arg'>optionkist</i></a></td></tr>
  48 <tr valign=top ><td ><a href="#13"><b class='cmd'>::mysql::col</b> <i class='arg'>handle</i> ?<i class='arg'>option</i>...?</a></td></tr>
  49 <tr valign=top ><td ><a href="#14"><b class='cmd'>::mysql::info</b> <i class='arg'>handle</i> <i class='arg'>option</i></a></td></tr>
  50 <tr valign=top ><td ><a href="#15"><b class='cmd'>::mysql::baseinfo</b> <i class='arg'>option</i></a></td></tr>
  51 <tr valign=top ><td ><a href="#16"><b class='cmd'>::mysql::ping</b> <i class='arg'>handle</i></a></td></tr>
  52 <tr valign=top ><td ><a href="#17"><b class='cmd'>::mysql::changeuser</b> <i class='arg'>user</i> <i class='arg'>password</i> ?<i class='arg'>database</i>?</a></td></tr>
  53 <tr valign=top ><td ><a href="#18"><b class='cmd'>::mysql::result</b> <i class='arg'>handle</i> <i class='arg'>option</i></a></td></tr>
  54 <tr valign=top ><td ><a href="#19"><b class='cmd'>::mysql::state</b> <i class='arg'>handle</i> ?<i class='arg'>-numeric</i>?</a></td></tr>
  55 <tr valign=top ><td ><a href="#20"><b class='cmd'>::mysql::close</b> ?<i class='arg'>handle</i>?</a></td></tr>
  56 <tr valign=top ><td ><a href="#21"><b class='cmd'>::mysql::insertid</b> <i class='arg'>handle</i></a></td></tr>
  57 <tr valign=top ><td ><a href="#22"><b class='cmd'>::mysql::escape</b> ?<i class='arg'>handle</i>? <i class='arg'>string</i></a></td></tr>
  58 <tr valign=top ><td ><a href="#23"><b class='cmd'>::mysql::autocommit</b> <i class='arg'>handle</i> <i class='arg'>boolean</i></a></td></tr>
  59 <tr valign=top ><td ><a href="#24"><b class='cmd'>::mysql::commit</b> <i class='arg'>handle</i></a></td></tr>
  60 <tr valign=top ><td ><a href="#25"><b class='cmd'>::mysql::rollback</b> <i class='arg'>handle</i></a></td></tr>
  61 <tr valign=top ><td ><a href="#26"><b class='cmd'>::mysql::nextresult</b> <i class='arg'>handle</i></a></td></tr>
  62 <tr valign=top ><td ><a href="#27"><b class='cmd'>::mysql::moreresult</b> <i class='arg'>handle</i></a></td></tr>
  63 <tr valign=top ><td ><a href="#28"><b class='cmd'>::mysql::warningcount</b> <i class='arg'>handle</i></a></td></tr>
  64 <tr valign=top ><td ><a href="#29"><b class='cmd'>::mysql::isnull</b> <i class='arg'>value</i></a></td></tr>
  65 <tr valign=top ><td ><a href="#30"><b class='cmd'>::mysql::newnull</b> </a></td></tr>
  66 <tr valign=top ><td ><a href="#31"><b class='cmd'>::mysql::setserveroption</b> <i class='arg'>handle</i> <i class='arg'>option</i></a></td></tr>
  67 <tr valign=top ><td ><a href="#32"><b class='cmd'>::mysql::shutdown</b> <i class='arg'>handle</i></a></td></tr>
  68 <tr valign=top ><td ><a href="#33"><b class='cmd'>::mysql::encoding</b> <i class='arg'>handle</i> ?encoding?</a></td></tr>
  69 </table></td></tr></table>
  70 <h2><a name="description">DESCRIPTION</a></h2>
  71 <p>
  72 MySQLTcl is a collection of Tcl commands and a Tcl global array that
  73 provide access to MySQL database servers.
  74 <p>
  75 MySQLTcl is nothing more than a patched version of a patched version
  76 of Hakan Soderstrom's patch of Tom Poindexter's Sybtcl.
  77 <p>
  78 Mysqltcl is binary Tcl library (extension) written in C language that use direkt
  79 official MySQL C-API. Almost all Tcl commands correspond to MySQL C-API functions.
  80 For detail documentation see official MySQL C-API manual.
  81
  82 <h2><a name="mysqltcl_commands">MYSQLTCL COMMANDS</a></h2>
  83 <p>
  84
  85 <dl>
  86
  87 <dt><a name="1"><b class='cmd'>::mysql::connect</b> ?<i class='arg'>option value</i>...?</a><dd>
  88
  89
  90 Connect to a MySQL server.
  91 A handle is returned which should be used in other mysqltcl
  92 commands using this connection.
  93 ::mysql::connect raises a Tcl error if the connection fails.
  94 ::mysql::connect read first the options from my.cnf file group mysqltcl.
  95 See MySQL documentation chapter &quot;options files&quot;.
  96 Possible connection options are:
  97
  98 <br><br>
  99 <dl>
 100
 101 <dt><strong>-host</strong> <i class='arg'>hostname</i><dd>
 102 The host on which the server is located. The local host is used by default.
 103
 104 <br><br>
 105 <dt><strong>-user</strong> <i class='arg'>user</i><dd>
 106 The user whose name is used for the connection.
 107 The current Unix user-name is used by default.
 108
 109 <br><br>
 110 <dt><strong>-password</strong> <i class='arg'>password</i><dd>
 111 The password that must be used for the connection.
 112 If it is not present, the connection is possible only for users with
 113 no password on the server.
 114
 115 <br><br>
 116 <dt><strong>-db</strong> <i class='arg'>db</i><dd>
 117 If this option is present, <i class='arg'>db</i> is used as current database, with no need
 118 for a call to <em>mysql::use</em>.
 119
 120 <br><br>
 121 <dt><strong>-port</strong> <i class='arg'>port</i><dd>
 122 The port number for the TCP/IP connection, if it's different from the default.
 123
 124 <br><br>
 125 <dt><strong>-socket</strong> <i class='arg'>socket</i><dd>
 126 The socket or named pipe for the connection.
 127
 128 <br><br>
 129 <dt><strong>-encoding</strong> <i class='arg'>encodingname</i><dd>
 130 The option works similar to -encoding option in fconfigure. It support also
 131 special encoding name binary. By option -binary no converting will be done be reading or writing to/from MySQL.
 132 If option is not set the system encoding (see utf-8) is used.
 133 Please test all input and outputs with another program to check that all
 134 is the way you expect it. If option binary is not used the system procedures
 135 Tcl_ExternalToUtfDString (writing) and Tcl_ExternalToUtf (reading) will be used
 136 by option binary the function Tcl_GetByteArrayFromObj and Tcl_NewByteArrayObj are used.
 137 If you want to manipulate binary date use -encoding binary. By handling textes set your
 138 special encoding that you want to use in your database. Consider what another system access the
 139 database and what encoding they expect. It can useful
 140 to use -encoding utf-8. That is standard encoding in some linux distributions and newer systems.
 141
 142 <br><br>
 143 <dt><strong>-compress</strong> <i class='arg'>boolean</i><dd>
 144 Use compression protocol. Default is false
 145
 146 <br><br>
 147 <dt><strong>-odbc</strong> <i class='arg'>boolean</i><dd>
 148 The client is an ODBC client. This changes mysqld to be more ODBC-friendly. Default is false
 149
 150 <br><br>
 151 <dt><strong>-noschema</strong> <i class='arg'>boolean</i><dd>
 152 Don't allow the db_name.tbl_name.col_name syntax. This is for ODBC. It causes the parser to generate an error if you use that syntax, which is useful for trapping bugs in some ODBC programs. This changes mysqld to be more ODBC-friendly. Default is false
 153
 154 <br><br>
 155 <dt><strong>-multistatement</strong> <i class='arg'>boolean</i><dd>
 156 Tell the server that the client may send multiple-row-queries (separated by `;').
 157 If this flag is not set, multiple-row-queries are disabled. Default is false.
 158
 159 <br><br>
 160 <dt><strong>-multiresult</strong> <i class='arg'>boolean</i><dd>
 161 Tell the server that the client can handle multiple-result sets from multi-queries or stored procedures.
 162 This is automatically set if CLIENT_MULTI_STATEMENTS is set.
 163
 164 <br><br>
 165 <dt><strong>-localfiles</strong> <i class='arg'>boolean</i><dd>
 166 Enable LOAD DATA LOCAL handling. Default is false.
 167
 168 <br><br>
 169 <dt><strong>-foundrows</strong> <i class='arg'>boolean</i><dd>
 170 Return the number of found (matched) rows, not the number of affected rows.
 171 Default is false.
 172
 173 <br><br>
 174 <dt><strong>-interactive</strong> <i class='arg'>boolean</i><dd>
 175 Allow interactive_timeout seconds (instead of wait_timeout seconds) of inactivity before closing the connection.
 176 The client's session wait_timeout variable will be set to the value of the session interactive_timeout variable.
 177 Default is false.
 178
 179 <br><br>
 180 <dt><strong>-ssl</strong> <i class='arg'>boolean</i><dd>
 181 Switch to SSL after handshake. Default is  false
 182
 183 <br><br>
 184 <dt><strong>-sslkey</strong> <i class='arg'>string</i><dd>
 185 is the pathname to the key file.
 186 Used if -ssl is true
 187
 188 <br><br>
 189 <dt><strong>-sslcert</strong> <i class='arg'>string</i><dd>
 190 is the pathname to the certificate file.
 191 Used if -ssl is true
 192
 193 <br><br>
 194 <dt><strong>-sslca</strong> <i class='arg'>string</i><dd>
 195 is the pathname to the certificate authority file.
 196 Used if -ssl is true
 197
 198 <br><br>
 199 <dt><strong>-sslcapath</strong> <i class='arg'>string</i><dd>
 200 is the pathname to a directory that contains trusted SSL CA certificates in pem format.
 201 Used if -ssl is true
 202
 203 <br><br>
 204 <dt><strong>-sslcipher</strong> <i class='arg'>string</i><dd>
 205 is a list of allowable ciphers to use for SSL encryption.
 206 Used if -ssl is true
 207
 208 </dl>
 209
 210 <dt><a name="2"><b class='cmd'>::mysql::use</b> <i class='arg'>handle</i> <i class='arg'>database</i></a><dd>
 211
 212
 213 Associate a connected handle with a particular database.
 214 <i class='arg'>handle</i> must be a valid handle previously obtained from ::mysql::connect.
 215 mysql::use raises a Tcl error if the handle is not valid or
 216 if the database name specified could not be used.
 217 <br><br>
 218 Consider you can use mysqltcl without to specify the database, in this case
 219 you must use explizit schema notation to specify the table in sql.
 220 <p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
 221 ::mysql::sel $handle {select * from uni.student}
 222 </pre></td></tr></table></p>
 223 with option connection <i class='arg'>-noschema</i> you can prohibit such syntax.
 224
 225 <br><br>
 226 <dt><a name="3"><b class='cmd'>::mysql::sel</b> <i class='arg'>handle</i> <i class='arg'>sql-statement</i> ?<i class='arg'>-list|-flatlist</i>?</a><dd>
 227
 228
 229 Send <i class='arg'>sql-statement</i> to the server.
 230 <br><br>
 231 If <i class='arg'>sql-statement</i> is a SELECT statement and no <i class='arg'>-list</i> or
 232 <i class='arg'>-flatlist</i> option is specified, the command returns the
 233 number of rows returned as the result of the query.
 234 The rows can be obtained by the <i class='arg'>::mysql::fetch</i> and/or the
 235 <i class='arg'>::mysql::map</i> commands.
 236 The resulting rows are called the <em>pending result</em>.
 237 <br><br>
 238 If <i class='arg'>sql-statement</i> is a SELECT statement and <i class='arg'>-list</i> or <i class='arg'>-flatlist</i>
 239 is specified, the command returns the full list of rows returned as
 240 the result of the query in one of two possible formats:
 241
 242 <br><br>
 243 <dl>
 244
 245 <dt><strong>-list</strong><dd>
 246 generates a list of lists, in which each element is a row of the result.
 247
 248 <br><br>
 249 <dt><strong>-flatlist</strong><dd>
 250 generates the concatenation of all rows in a single list, which
 251 is useful for scanning with a single <em>foreach</em>.
 252
 253 </dl>
 254
 255 Example:
 256
 257 <p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
 258 % ::mysql::sel $db &quot;SELECT ID, NAME FROM FRIENDS&quot; -list
 259 {1 Joe} {2 Phil} {3 John}
 260 % ::mysql::sel $db &quot;SELECT ID, NAME FROM FRIENDS&quot; -flatlist
 261 {1 Joe 2 Phil 3 John}
 262 </pre></td></tr></table></p>
 263
 264 Note that both list syntaxes are faster than something like
 265
 266 <p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
 267 % ::mysql::sel $db &quot;SELECT ID, NAME FROM FRIENDS&quot;
 268 % ::mysql::map $db {id name} {lappend result $id $name}
 269 % set $result
 270 {1 Joe 2 Phil 3 John}
 271 </pre></td></tr></table></p>
 272
 273 If <i class='arg'>sql-statement</i> is a valid MySQL statement, but not a SELECT
 274 statement, the command returns -1 after executing the statement, or an empty
 275 string if <i class='arg'>-list</i> or <i class='arg'>-flatlist</i> is specified.
 276 There is no pending result in this case.
 277 <br><br>
 278 In any case ::mysql::sel implicitly cancels any previous result still
 279 pending for the handle.
 280
 281 <br><br>
 282 <dt><a name="4"><b class='cmd'>::mysql::fetch</b> <i class='arg'>handle</i></a><dd>
 283
 284
 285 Returns the next row from result set as Tcl list.
 286 mysql::fetch raises a Tcl error if there is no pending result for <i class='arg'>handle</i>.
 287 mysql::fetch was former named mysqlnext.
 288
 289 <br><br>
 290 <dt><a name="5"><b class='cmd'>::mysql::exec</b> <i class='arg'>handle</i> <i class='arg'>sql-statement</i></a><dd>
 291
 292
 293 Send <i class='arg'>sql-statement</i>, a MySQL non-SELECT statement, to the server.
 294 The <i class='arg'>handle</i> must be in use (through ::mysql::connect and ::mysql::use).
 295 <br><br>
 296 ::mysql::exec implicitly cancels any previous result pending for the handle.
 297 <br><br>
 298 If <i class='arg'>sql-statement</i> is a valid MySQL SELECT statement, the statement
 299 is executed, but the result is discarded.
 300 No Tcl error is generated.
 301 This amounts to a (potentially costly) no-op.
 302 Use the ::mysql::sel command for SELECT statements.
 303 <br><br>
 304 ::mysql::exec returns the number of affected rows (DELETE, UPDATE).
 305 In case of multiple statement ::mysql::exec returns a list of number of affected rows.
 306 <br><br>
 307
 308 <br><br>
 309 <dt><a name="6"><b class='cmd'>::mysql::query</b> <i class='arg'>handle</i> <i class='arg'>sql-select-statement</i></a><dd>
 310
 311
 312 Send <i class='arg'>sql-select-statement</i> to the server.
 313 <br><br>
 314 <i class='arg'>mysql::query</i> allow to send multiple nested queries on one handle (without need to build
 315 new handle or caching results).
 316 mysql::query return a query handle that can be used as handle in commands as (mysql::fetch,
 317 ::mysql::map, mysql::seek, mysql::col, mysql::result).
 318 After result proceeding all query must be
 319 freed with <em>::mysql::endquery query-hanlde</em> command.
 320 <br><br>
 321 Example:
 322 <p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
 323 set query1 [::mysql::query $db {SELECT ID, NAME FROM FRIENDS}\]
 324 while {[set row [::mysql::fetch $query1]]!=&quot;&quot;} {
 325     set id [lindex $row 0]
 326     set query2 [::mysql::query $db &quot;SELECT ADDRESS FROM ADDRESS WHERE FRIENDID=$ID&quot;]
 327     ::mysql::map $query2 address { puts &quot;address = $address&quot; }
 328     ::mysql::endquery $query2
 329 }
 330 ::mysql::endquery $query1
 331 </pre></td></tr></table></p>
 332 In most cases one should use sql-joins and avoid nested queries.
 333 SQL-sever can optimize such queries.
 334 But in some applications (GUI-Forms) where the results are used long time the inner
 335 query is not known before.
 336
 337 <br><br>
 338 <dt><a name="7"><b class='cmd'>::mysql::endquery</b> <i class='arg'>query-handle</i></a><dd>
 339
 340
 341 free result memory after <i class='arg'>::mysql::query</i> command.
 342 You must invoke ::mysql::endquery after each mysqlquery to not cause memory leaks. See mysqlquery command.
 343 <br><br>
 344 Using <i class='arg'>::mysql::endquery</i> on db-handle will free also memory (pending result) after <i class='arg'>::mysql::sel</i> command.
 345 <br><br>
 346
 347
 348 <br><br>
 349 <dt><a name="8"><b class='cmd'>::mysql::map</b> <i class='arg'>handle</i> <i class='arg'>binding-list</i> <i class='arg'>script</i></a><dd>
 350
 351
 352 Iterate a script over the rows of the pending result.
 353 ::mysql::map may consume all rows or only some of the rows of the pending
 354 result.
 355 Any remaining rows may be obtained by further ::mysql::fetch or ::mysql::map
 356 commands.
 357 <br><br>
 358 <i class='arg'>handle</i> must be a handle with a pending result from a previous
 359 ::mysql::sel command.
 360 <i class='arg'>binding-list</i> must be a list of one or more variable names.
 361 <i class='arg'>script</i> must be a Tcl script.
 362 It may be empty, but usually it contains one or more commands.
 363 <br><br>
 364 ::mysql::map processes one row at a time from the pending result.
 365 For each row the column values are bound to the variables in the
 366 binding list, then the script is executed.
 367 Binding is strictly positional.
 368 The first variable in the binding list is bound to the first column of
 369 the row, and so on.
 370 The variables are created in the current context (if they do not
 371 already exist).
 372 A variable name begining with a hyphen is not bound; it serves as a
 373 placeholder in the binding list.
 374 If there are more columns than variables the extra columns are
 375 ignored.
 376 <br><br>
 377 The ::mysql::map command is similar to an ordinary <em>foreach</em>.
 378 A <em>foreach</em> iterates over the elements of a list, ::mysql::map
 379 iterates over the rows of a pending result.
 380 In both cases iteration is affected by <em>break</em> and <em>continue</em>
 381 Tcl commands.
 382 The binding list variables retain their last values after the command
 383 has completed.
 384 <br><br>
 385 A simple example follows.
 386 Assume $db is a handle in use.
 387 <p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
 388 ::mysql::sel $db {
 389     select lname, fname, area, phone from friends order by lname, fname
 390 }
 391 ::mysql::map $db {ln fn - phone} {
 392    if {$phone == {}} continue
 393    puts [format &quot;%16s %-8s %s&quot; $ln $fn $phone]
 394 }
 395 </pre></td></tr></table></p>
 396 The ::mysql::sel command gets and sorts all rows from table friends.
 397 The ::mysql::map command is used to format and print the result in a way
 398 suitable for a phone list.
 399 For demonstration purposes one of the columns (area) is not used.
 400 The script begins by skipping over rows which have no phone number.
 401 The second command in the script formats and prints values from the row.
 402 <br><br>
 403 ::mysql::map raises a Tcl error if there is no pending result for
 404 <i class='arg'>handle</i>, or if <i class='arg'>binding-list</i> contains more variables than
 405 there are columns in the pending result.
 406 <br><br>
 407
 408 <br><br>
 409 <dt><a name="9"><b class='cmd'>::mysql::receive</b> <i class='arg'>handle</i> <i class='arg'>sql-statment</i> <i class='arg'>binding-list</i> <i class='arg'>script</i></a><dd>
 410
 411
 412 This command works the same way as the command mysqtclmap but
 413 it do not need leading ::mysql::sel command.
 414 The main difference is internal using of MySQL client library.
 415 This command use mysql_use_result from C-API that do not
 416 store result on client but try to receive the rows directly
 417 from server.
 418 There is also no client cache.
 419 This command can be faster as using of ::mysql::sel and by
 420 very big resultset will not overload client machine.
 421 The scipt should process the result immadiatly because
 422 it can block table (or tables) for another clients.
 423 If performance matter please test all alternatives separatly.
 424 You must consider two aspects: memory consumption and performance.
 425
 426 <br><br>
 427 <dt><a name="10"><b class='cmd'>::mysql::seek</b> <i class='arg'>handle</i> <i class='arg'>row-index</i></a><dd>
 428
 429
 430 Moves the current position among the rows in the pending result.
 431 This may cause <em>::mysql::fetch</em> and <em>::mysql::map</em> to re-read rows, or to
 432 skip over rows.
 433 <br><br>
 434 Row index 0 is the position just before the first row in the pending result;
 435 row index 1 is the position just before the second row, and so
 436 on.
 437 You may specify a negative row index.
 438 Row index -1 is the position just before the last row;
 439 row index -2 is the position just before the second last row,
 440 and so on.
 441 An out-of-bounds row index will cause ::mysql::seek to set the new current
 442 position either just before the first row (if the index is too negative),
 443 or just after the last row (if the index exceeds the number of rows).
 444 This is not an error condition.
 445 <br><br>
 446 ::mysql::seek returns the number of rows that can be read sequentially from
 447 the new current position.
 448 ::mysql::seek raises a Tcl error if there is no pending result for <i class='arg'>handle</i>.
 449 <br><br>
 450 Portability note: The functionality of <i class='arg'>::mysql::seek</i> is frequently
 451 absent in other Tcl extensions for SQL.
 452 That is because MySQL C-API client library ofers own result set caching functionality
 453 that lacks another SQL-APIs.
 454 That increase the performance because all rows are received at once and the query does
 455 not block the server for another clienst , on the other
 456 hand you works on the cached data can use a lot of memory and are up to date only in the moment
 457 of query but not fetch.
 458 <br><br>
 459
 460 <br><br>
 461 <dt><a name="11"><b class='cmd'>::mysql::col</b> <i class='arg'>handle</i> <i class='arg'>table-name</i> <i class='arg'>option</i></a><dd>
 462
 463 <dt><a name="12"><b class='cmd'>::mysql::col</b> <i class='arg'>handle</i> <i class='arg'>table-name</i> <i class='arg'>optionkist</i></a><dd>
 464
 465 <dt><a name="13"><b class='cmd'>::mysql::col</b> <i class='arg'>handle</i> ?<i class='arg'>option</i>...?</a><dd>
 466
 467
 468 Return information about the columns of a table.
 469 <i class='arg'>handle</i> must be in use.
 470 <i class='arg'>table-name</i> must be the name of a table; it may be a table name
 471 or <i class='arg'>-current</i> if there is a pending result.
 472 One or more options control what information to return.
 473 Each option must be one of the following keywords.
 474 <br><br>
 475 <dl>
 476
 477 <dt><strong>name</strong><dd> Return the name of a column.
 478
 479 <br><br>
 480 <dt><strong>type</strong><dd>
 481 Return the type of a column; one of the strings <em>decimal</em>,
 482 <em>tiny</em>, <em>short</em>, <em>long</em>, <em>float</em>, <em>double</em>,
 483 <em>null</em>, <em>timestamp</em>, <em>long long</em>, <em>int24</em>, <em>date</em>,
 484 <em>time</em>, <em>date time</em>, <em>year</em>, <em>new date</em>, <em>enum</em>,
 485 <em>set</em>, <em>tiny blob</em>, <em>medium blob</em>, <em>long blob</em>,
 486 <em>blob</em>, <em>var string</em>, or <em>string</em>.
 487 Note that a column of type <em>char</em> will return tiny, while they are
 488 represented equally.
 489
 490 <br><br>
 491 <dt><strong>length</strong><dd> Return the length of a column in bytes.
 492
 493 <br><br>
 494 <dt><strong>table</strong><dd> Return the name of the table in which this column occurs.
 495
 496 <br><br>
 497 <dt><strong>non_null</strong><dd> Return the string &quot;1&quot; if the column is non-null; otherwise &quot;0&quot;.
 498
 499 <br><br>
 500 <dt><strong>prim_key</strong><dd> Return the string &quot;1&quot; if the column is part of the primary key;
 501 otherwise &quot;0&quot;.
 502
 503 <br><br>
 504 <dt><strong>numeric</strong><dd> Return the string &quot;1&quot; if the column is numeric; otherwise &quot;0&quot;.
 505
 506 <br><br>
 507 <dt><strong>decimals</strong><dd> Return the string &quot;1&quot; if the column is non-null; otherwise &quot;0&quot;.
 508 </dl>
 509
 510 The three forms of this command generate their result in a
 511 particular way.
 512 <br><br>
 513 <ol>
 514 <li>
 515 If a single option is present the result is a simple list of
 516 values; one for each column.
 517 <br><br>
 518 <li>
 519 If the options are given in the form of an option list the
 520 result is a list of lists.
 521 Each sublist corresponds to a column and contains the information
 522 specified by the options.
 523 <br><br>
 524 <li>
 525 If several options are given, but not in a list, the result is also
 526 a list of lists.
 527 In this case each sublist corresponds to an option and contains one
 528 value for each column.
 529 </ol>
 530
 531 The following is a sample interactive session containing all forms of
 532 the ::mysql::col command and their results.
 533 The last command uses the <em>-current</em> option.
 534 It could alternatively specify the table name explicitly.
 535 <p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
 536 %::mysql::col $db friends name
 537 name lname area phone
 538 % ::mysql::col $db friends {name type length}
 539 {fname char 12} {lname char 20} {area char 5} {phone char 12}
 540 % ::mysql::sel $db {select * from friends}
 541 % ::mysql::col $db -current name type length
 542 {fname lname area phone} {char char char char} {12 20 5 12}]
 543 </pre></td></tr></table></p>
 544
 545 <br><br>
 546 <dt><a name="14"><b class='cmd'>::mysql::info</b> <i class='arg'>handle</i> <i class='arg'>option</i></a><dd>
 547
 548
 549 Return various database information depending on the <i class='arg'>option</i>.
 550 The option must be one of the following keywords.
 551
 552 <br><br>
 553 <dl>
 554 <dt><strong>info</strong><dd>
 555 Return a String with information about last operation.
 556 &quot;Records: 3 Duplicates: 0 Warnings: 0&quot; by INSERT or
 557 &quot;Rows matched: 40 Changed: 40 Warnings: 0&quot; by UPDATE statements
 558 (read the manual for mysql_info in MySQL C API documentation)
 559
 560 <br><br>
 561 <dt><strong>databases</strong><dd>
 562 Return a list of all database names known to the server.
 563 The handle must be connected.
 564
 565 <br><br>
 566 <dt><strong>dbname</strong><dd>
 567 Return the name of the database with which the handle is associated.
 568 The handle must be in use.
 569
 570 <br><br>
 571 <dt><strong>dbname?</strong><dd>
 572 Return the name of the database with which the handle is associated;
 573 an empty string if the handle is connected, but not in use.
 574
 575 <br><br>
 576 <dt><strong>host</strong><dd>
 577 Return the name of the host to which the handle is connected.
 578 The handle must be connected.
 579
 580 <br><br>
 581 <dt><strong>host</strong><dd>
 582 Return the name of the host to which the handle is connected; an empty
 583 string if the handle is not valid.
 584
 585 <br><br>
 586 <dt><strong>tables</strong><dd>
 587 Return a list of all table names in the database with which the handle
 588 is associated.
 589 The handle must be in use.
 590
 591 <br><br>
 592 <dt><strong>serverversion</strong><dd>
 593 Returns the version number of the server as a string.
 594
 595 <br><br>
 596 <dt><strong>serverversionid</strong><dd>
 597 Returns the version number of the server as an integer.
 598
 599 <br><br>
 600 <dt><strong>sqlstate</strong><dd>
 601 Returns a string containing the SQLSTATE error code for the last error.
 602 The error code consists of five characters. '00000' means ``no error.''
 603 The values are specified by ANSI SQL and ODBC.
 604
 605 Note that not all MySQL errors are yet mapped to SQLSTATE's.
 606 The value 'HY000' (general error) is used for unmapped errors.
 607
 608 <br><br>
 609 <dt><strong>state</strong><dd>
 610 Returns a character string containing information similar to that provided by the mysqladmin status command.
 611 This includes uptime in seconds and the number of running threads, questions, reloads, and open tables.
 612
 613 </dl>
 614
 615 <dt><a name="15"><b class='cmd'>::mysql::baseinfo</b> <i class='arg'>option</i></a><dd>
 616
 617
 618 return information information that do not need handle.
 619 <br><br>
 620 <dl>
 621
 622 <dt><strong>connectparameters</strong><dd>
 623 return all supported connecting options
 624
 625 <br><br>
 626 <dt><strong>clientversion</strong><dd>
 627 return the version of underlying MYSQL C-API library
 628 </dl>
 629
 630 <dt><a name="16"><b class='cmd'>::mysql::ping</b> <i class='arg'>handle</i></a><dd>
 631
 632
 633 Checks whether the connection to the server is working. If it has gone down, an automatic reconnection is attempted.
 634 <br><br>
 635 This function can be used by clients that remain idle for a long while, to check whether the server has closed the connection and reconnect if necessary.
 636 <br><br>
 637 Return True if server is alive
 638
 639 <br><br>
 640 <dt><a name="17"><b class='cmd'>::mysql::changeuser</b> <i class='arg'>user</i> <i class='arg'>password</i> ?<i class='arg'>database</i>?</a><dd>
 641
 642
 643 Changes the user and causes the database specified by database to become the default (current) database on the connection specified by MySQL. In subsequent queries, this database is the default for table references that do not include an explicit database specifier.
 644 <br><br>
 645 ::mysql::changeuser fails unless the connected user can be authenticated or if he doesn't have permission to use the database. In this case the user and database are not changed
 646 <br><br>
 647 if database parameter may be set were is no default database.
 648 <br><br>
 649 Cause Error if operation is not succesed
 650
 651 <br><br>
 652 <dt><a name="18"><b class='cmd'>::mysql::result</b> <i class='arg'>handle</i> <i class='arg'>option</i></a><dd>
 653
 654
 655 Return information about the pending result.
 656 Note that a result is pending until canceled by a ::mysql::exec command,
 657 even if no rows remain to be read.
 658 <i class='arg'>Option</i> must be one of the following keywords.
 659
 660 <br><br>
 661 <dl>
 662
 663 <dt><strong>cols</strong><dd>
 664 Return the number of columns in the pending result.
 665 There must be a pending result.
 666
 667 <br><br>
 668 <dt><strong>cols</strong><dd>
 669 Return the number of columns in the pending result; an empty string if
 670 no result is pending.
 671
 672 <br><br>
 673 <dt><strong>current</strong><dd>
 674 Return the current position in the pending result; a non-negative integer.
 675 This value can be used as <i class='arg'>row-index</i> in the ::mysql::seek command.
 676 An error is raised if there is no pending result.
 677
 678 <br><br>
 679 <dt><strong>current?</strong><dd>
 680 As above, but returns an empty string if there is no pending result.
 681
 682 <br><br>
 683 <dt><strong>rows</strong><dd>
 684 Return the number of rows that can be read sequentially from the
 685 current position in the pending result.
 686 There must be a pending result.
 687
 688 <br><br>
 689 <dt><strong>rows</strong><dd>
 690 Return the number of rows that can be read sequentially from the
 691 current position in the pending result; an empty string if no result
 692 is pending.
 693 <br><br>
 694 [::mysql::result $db current] + [::mysql::result $db rows]
 695 always equals the total number of rows in the pending result.
 696 </dl>
 697
 698 <dt><a name="19"><b class='cmd'>::mysql::state</b> <i class='arg'>handle</i> ?<i class='arg'>-numeric</i>?</a><dd>
 699
 700
 701 Return the state of a handle as a string or in numeric form.
 702 There is no requirement on <i class='arg'>handle</i>; it may be any string.
 703 The return value is one of the following strings, or the corresponding
 704 numeric value if <i class='arg'>-numeric</i> is specified.
 705 The states form a progression where each state builds on the previous.
 706 <br><br>
 707 <dl>
 708
 709 <dt><strong>NOT_A_HANDLE (0)</strong><dd>
 710 The string supplied for <i class='arg'>handle</i> is not a mysqltcl handle at all.
 711
 712 <br><br>
 713 <dt><strong>UNCONNECTED (1)</strong><dd>
 714 The string supplied for <i class='arg'>handle</i> is one of the possible mysqltcl
 715 handles, but it is not valid to any server.
 716
 717 <br><br>
 718 <dt><strong>CONNECTED (2)</strong><dd>
 719 The handle is connected to a server, but not associated with a database.
 720
 721 <br><br>
 722 <dt><strong>IN_USE (3)</strong><dd>
 723 The handle is connected and associated with a database, but there is
 724 no pending result.
 725
 726 <br><br>
 727 <dt><strong>RESULT_PENDING (4)</strong><dd>
 728 The handle is connected, associated with a database, and there is a
 729 pending result.
 730 </dl>
 731
 732 <dt><a name="20"><b class='cmd'>::mysql::close</b> ?<i class='arg'>handle</i>?</a><dd>
 733
 734
 735 Closes the server connection associated with <i class='arg'>handle</i>, causing it
 736 to go back to the unconnected state.
 737 Closes all connections if <i class='arg'>handle</i> is omitted.
 738 Returns an empty string.
 739 ::mysql::close raises a Tcl error if a handle is specified which is not
 740 valid.
 741
 742 <br><br>
 743 <dt><a name="21"><b class='cmd'>::mysql::insertid</b> <i class='arg'>handle</i></a><dd>
 744
 745
 746 Returns the auto increment id of the last INSERT statement.
 747
 748 <br><br>
 749 <dt><a name="22"><b class='cmd'>::mysql::escape</b> ?<i class='arg'>handle</i>? <i class='arg'>string</i></a><dd>
 750
 751
 752 Returns the content of <i class='arg'>string</i>, with all special characters escaped,
 753 so that it is suitable for use in an SQL statement. This is simpler (faster)
 754 than using a general <em>regexp</em> or string map.
 755 If handle is specified C-API function mysql_real_escape_string is used.
 756 This is the recommended usage because in this case current character set is respected.
 757
 758 <br><br>
 759 <dt><a name="23"><b class='cmd'>::mysql::autocommit</b> <i class='arg'>handle</i> <i class='arg'>boolean</i></a><dd>
 760
 761 Sets autocommit mode on if mode is 1, off if mode is 0.
 762
 763 <br><br>
 764 <dt><a name="24"><b class='cmd'>::mysql::commit</b> <i class='arg'>handle</i></a><dd>
 765
 766 Commits the current transaction.
 767
 768 <br><br>
 769 <dt><a name="25"><b class='cmd'>::mysql::rollback</b> <i class='arg'>handle</i></a><dd>
 770
 771 Rollback the current transaction.
 772
 773 <br><br>
 774 <dt><a name="26"><b class='cmd'>::mysql::nextresult</b> <i class='arg'>handle</i></a><dd>
 775
 776 If more query results exist, mysql::nextresult() reads the next query results and returns the status back to application.
 777 returns -1 if no result or number of rows in the result set.
 778
 779 <br><br>
 780 <dt><a name="27"><b class='cmd'>::mysql::moreresult</b> <i class='arg'>handle</i></a><dd>
 781
 782 Returns true if more results exist from the currently executed query, and the application must call mysql::result to fetch the results.
 783
 784 <br><br>
 785 <dt><a name="28"><b class='cmd'>::mysql::warningcount</b> <i class='arg'>handle</i></a><dd>
 786
 787 Returns the number of warnings generated during execution of the previous SQL statement.
 788
 789
 790 <br><br>
 791 <dt><a name="29"><b class='cmd'>::mysql::isnull</b> <i class='arg'>value</i></a><dd>
 792
 793 Null handling is a known problem with Tcl, especially with DB interaction.
 794 The mysql &quot;varchar&quot; type has two valid blank values, NULL and an empty
 795 string. This is where the problem arises; Tcl is not able to differentiate
 796 between the two because of the way it handles strings.
 797 Mysql has new internal Tcl type for null that string representation is stored
 798 in global array mysqltcl(nullvalue) and as default empty string.
 799 mysql::isnull can be used for safe check for null value.
 800 Warning mysql::isnull works only reliable if there are no type conversation on
 801 returned rows.
 802 Consider row is always Tcl list even when there are only one column in the row.
 803 <p><table><tr><td bgcolor=black>&nbsp;</td><td><pre class='sample'>
 804 set row [::mysql::next $handle]
 805 if {[mysql::isnull [lindex $row 1]]} {
 806    puts &quot;2. column of $row is null&quot;
 807 }
 808 if {[mysql::isnull $row]} {
 809    puts &quot;this does not work, because of type conversation list to string&quot;
 810 }
 811 </pre></td></tr></table></p>
 812
 813 <br><br>
 814 <dt><a name="30"><b class='cmd'>::mysql::newnull</b> </a><dd>
 815
 816 create new null object. It can be used to simulate returned row contents.
 817
 818 <br><br>
 819 <dt><a name="31"><b class='cmd'>::mysql::setserveroption</b> <i class='arg'>handle</i> <i class='arg'>option</i></a><dd>
 820
 821 there are only 2 options now: -multi_statment_on and -multi_statment_off
 822
 823 <br><br>
 824 <dt><a name="32"><b class='cmd'>::mysql::shutdown</b> <i class='arg'>handle</i></a><dd>
 825
 826 Asks the database server to shut down. The connected user must have SHUTDOWN privileges.
 827
 828 <br><br>
 829 <dt><a name="33"><b class='cmd'>::mysql::encoding</b> <i class='arg'>handle</i> ?encoding?</a><dd>
 830
 831 Ask or change a encoding of connection.
 832 There are special encoding &quot;binary&quot; for binary data transfers.
 833
 834 </dl>
 835
 836 <h2><a name="status_information">STATUS INFORMATION</a></h2>
 837 <p>
 838 Mysqltcl creates and maintains a Tcl global array to provide status
 839 information.
 840 Its name is <em>mysqlstatus</em>.
 841 .P
 842 Mysqlstatus elements:
 843 <dl>
 844 <dt>code<dd>
 845
 846 A numeric conflict code set after every mysqltcl command.
 847 Zero means no conflict; non-zero means some kind of conflict.
 848 All conflicts also generate a Tcl error.
 849 <br><br>
 850 All MySQL server conflicts set mysqlstatus(code) to the numeric
 851 code of the MySQL error.
 852 <br><br>
 853 Any other conflict sets mysqlstatus(code) to -1.
 854
 855 <br><br>
 856 <dt>command<dd>
 857 The last failing mysqltcl command.
 858 Not updated for successful commands.
 859
 860 <br><br>
 861 <dt>message<dd>
 862 Message string for the last conflict detected.
 863 The same string is returned as the result of the failing mysqltcl
 864 command.
 865 Not updated for successful commands.
 866
 867 <br><br>
 868 <dt>nullvalue<dd>
 869 The string to use in query results to represent the SQL null value.
 870 The empty string is used initially.
 871 You may set it to another value.
 872 </dl>
 873
 874 <h2><a name="backward_compatibility">Backward compatibility</a></h2>
 875 <p>
 876 Up from version 3.0 all mysql commands are declared in ::mysql namespace.
 877 All names for example mysqlconnect are also aviable but deprecated.
 878 All old commands have the name pattern mysql{name} and the most of them are now mysql::{name}.
 879 The exception is mysqlnext, which  was renamed to mysql::fetch.
 880
 881 <h2><a name="bugs_&amp;_possible_misfeatures">BUGS &amp; POSSIBLE MISFEATURES</a></h2>
 882 <p>
 883
 884 Deleting any of the mysqltcl commands closes all connections.
 885
 886 <h2><a name="authors">AUTHORS</a></h2>
 887 <p>
 888
 889 <ul>
 890 <li>
 891 Tobias Ritzau
 892 <br><br>
 893 <li>
 894 Paolo Brutti
 895 <br><br>
 896 <li>
 897 Artur Trzewik (mail@xdobry.de) - active maintainer
 898
 899 </ul>
 900
 901 MySQLTcl is derived from a patch of msql by Hakan Soderstrom, Soderstrom Programvaruverkstad,
 902 S-12242 Enskede, Sweden.
 903 msql is derived from Sybtcl by Tom Poindexter.
 904 There are many contributors and bug reporter that are not mentioned.
 905 If you have contributed to mysqltcl and wants to be on the list contact Artur Trzewik.
 906 </body></html>
 907