doc/mysqltcl.man

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