Imported Upstream version 3.05
[sven/mysqltcl.git] / 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 [list_end]
160
161 [call [cmd ::mysql::use] [arg handle] [arg database]]
162
163 Associate a connected handle with a particular database.
164 [arg handle] must be a valid handle previously obtained from ::mysql::connect.
165 mysql::use raises a Tcl error if the handle is not valid or
166 if the database name specified could not be used.
167 [nl]
168 Consider you can use mysqltcl without to specify the database, in this case
169 you must use explizit schema notation to specify the table in sql.
170 [example_begin]
171 ::mysql::sel $handle {select * from uni.student}
172 [example_end]
173 with option connection [arg -noschema] you can prohibit such syntax.
174
175 [call [cmd ::mysql::sel] [arg handle] [arg sql-statement] [opt [arg -list|-flatlist]]]
176
177 Send [arg sql-statement] to the server.
178 [nl]
179 If [arg sql-statement] is a SELECT statement and no [arg -list] or
180 [arg -flatlist] option is specified, the command returns the
181 number of rows returned as the result of the query.
182 The rows can be obtained by the [arg ::mysql::fetch] and/or the
183 [arg ::mysql::map] commands.
184 The resulting rows are called the [term "pending result"].
185 [nl]
186 If [arg sql-statement] is a SELECT statement and [arg -list] or [arg -flatlist]
187 is specified, the command returns the full list of rows returned as 
188 the result of the query in one of two possible formats:
189
190 [list_begin opt]
191
192 [opt_def -list]
193 generates a list of lists, in which each element is a row of the result.
194
195 [opt_def -flatlist]
196 generates the concatenation of all rows in a single list, which 
197 is useful for scanning with a single [emph foreach].
198
199 [list_end]
200
201 Example:
202
203 [example_begin]
204 % ::mysql::sel $db "SELECT ID, NAME FROM FRIENDS" -list
205 {1 Joe} {2 Phil} {3 John}
206 % ::mysql::sel $db "SELECT ID, NAME FROM FRIENDS" -flatlist
207 {1 Joe 2 Phil 3 John}
208 [example_end]
209
210 Note that both list syntaxes are faster than something like
211
212 [example_begin]
213 % ::mysql::sel $db "SELECT ID, NAME FROM FRIENDS"
214 % ::mysql::map $db {id name} {lappend result $id $name}
215 % set $result
216 {1 Joe 2 Phil 3 John}
217 [example_end]
218
219 If [arg sql-statement] is a valid MySQL statement, but not a SELECT
220 statement, the command returns -1 after executing the statement, or an empty 
221 string if [arg -list] or [arg -flatlist] is specified.
222 There is no pending result in this case.
223 [nl]
224 In any case ::mysql::sel implicitly cancels any previous result still
225 pending for the handle.
226
227 [call [cmd ::mysql::fetch] [arg handle]]
228
229 Returns the next row from result set as Tcl list.
230 mysql::fetch raises a Tcl error if there is no pending result for [arg handle].
231 mysql::fetch was former named mysqlnext.
232
233 [call [cmd ::mysql::exec] [arg handle] [arg sql-statement]]
234
235 Send [arg sql-statement], a MySQL non-SELECT statement, to the server.
236 The [arg handle] must be in use (through ::mysql::connect and ::mysql::use).
237 [nl]
238 ::mysql::exec implicitly cancels any previous result pending for the handle.
239 [nl]
240 If [arg sql-statement] is a valid MySQL SELECT statement, the statement
241 is executed, but the result is discarded.
242 No Tcl error is generated.
243 This amounts to a (potentially costly) no-op.
244 Use the ::mysql::sel command for SELECT statements.
245 [nl]
246 ::mysql::exec returns the number of affected rows (DELETE, UPDATE).
247 In case of multiple statement ::mysql::exec returns a list of number of affected rows.
248 [nl]
249
250 [call [cmd ::mysql::query] [arg handle] [arg sql-select-statement]]
251
252 Send [arg sql-select-statement] to the server.
253 [nl]
254 [arg mysql::query] allow to send multiple nested queries on one handle (without need to build
255 new handle or caching results).
256 mysql::query return a query handle that can be used as handle in commands as (mysql::fetch,
257 ::mysql::map, mysql::seek, mysql::col, mysql::result).
258 After result proceeding all query must be
259 freed with [emph "::mysql::endquery query-hanlde"] command.
260 [nl]
261 Example:
262 [example_begin]
263 set query1 [lb]::mysql::query $db {SELECT ID, NAME FROM FRIENDS}\[rb]
264 while {[lb]set row [lb]::mysql::fetch $query1[rb][rb]!=""} {
265     set id [lb]lindex $row 0[rb]
266     set query2 [lb]::mysql::query $db "SELECT ADDRESS FROM ADDRESS WHERE FRIENDID=$ID"[rb]
267     ::mysql::map $query2 address { puts "address = $address" }
268     ::mysql::endquery $query2
269 }
270 ::mysql::endquery $query1
271 [example_end]
272 In most cases one should use sql-joins and avoid nested queries.
273 SQL-sever can optimize such queries.
274 But in some applications (GUI-Forms) where the results are used long time the inner
275 query is not known before.
276
277 [call [cmd ::mysql::endquery] [arg query-handle]]
278
279 free result memory after [arg ::mysql::query] command.
280 You must invoke ::mysql::endquery after each mysqlquery to not cause memory leaks. See mysqlquery command.
281 [nl]
282 Using [arg ::mysql::endquery] on db-handle will free also memory (pending result) after [arg ::mysql::sel] command.
283 [nl]
284
285
286 [call [cmd ::mysql::map] [arg handle] [arg binding-list] [arg script]]
287
288 Iterate a script over the rows of the pending result.
289 ::mysql::map may consume all rows or only some of the rows of the pending
290 result.
291 Any remaining rows may be obtained by further ::mysql::fetch or ::mysql::map
292 commands.
293 [nl]
294 [arg handle] must be a handle with a pending result from a previous
295 ::mysql::sel command.
296 [arg binding-list] must be a list of one or more variable names.
297 [arg script] must be a Tcl script.
298 It may be empty, but usually it contains one or more commands.
299 [nl]
300 ::mysql::map processes one row at a time from the pending result.
301 For each row the column values are bound to the variables in the
302 binding list, then the script is executed.
303 Binding is strictly positional.
304 The first variable in the binding list is bound to the first column of
305 the row, and so on.
306 The variables are created in the current context (if they do not
307 already exist).
308 A variable name begining with a hyphen is not bound; it serves as a
309 placeholder in the binding list.
310 If there are more columns than variables the extra columns are
311 ignored.
312 [nl]
313 The ::mysql::map command is similar to an ordinary [emph foreach].
314 A [emph foreach] iterates over the elements of a list, ::mysql::map
315 iterates over the rows of a pending result.
316 In both cases iteration is affected by [emph break] and [emph continue]
317 Tcl commands.
318 The binding list variables retain their last values after the command
319 has completed.
320 [nl]
321 A simple example follows.
322 Assume $db is a handle in use.
323 [example_begin]
324 ::mysql::sel $db {
325     select lname, fname, area, phone from friends order by lname, fname
326 }
327 ::mysql::map $db {ln fn - phone} {
328    if {$phone == {}} continue
329    puts [lb]format "%16s %-8s %s" $ln $fn $phone[rb]
330 }
331 [example_end]
332 The ::mysql::sel command gets and sorts all rows from table friends.
333 The ::mysql::map command is used to format and print the result in a way
334 suitable for a phone list.
335 For demonstration purposes one of the columns (area) is not used.
336 The script begins by skipping over rows which have no phone number.
337 The second command in the script formats and prints values from the row.
338 [nl]
339 ::mysql::map raises a Tcl error if there is no pending result for
340 [arg handle], or if [arg binding-list] contains more variables than
341 there are columns in the pending result.
342 [nl]
343
344 [call [cmd ::mysql::receive] [arg handle] [arg sql-statment] [arg binding-list] [arg script]]
345
346 This command works the same way as the command mysqtclmap but
347 it do not need leading ::mysql::sel command.
348 The main difference is internal using of MySQL client library.
349 This command use mysql_use_result from C-API that do not
350 store result on client but try to receive the rows directly
351 from server.
352 There is also no client cache.
353 This command can be faster as using of ::mysql::sel and by
354 very big resultset will not overload client machine.
355 The scipt should process the result immadiatly because
356 it can block table (or tables) for another clients.
357 If performance matter please test all alternatives separatly.
358 You must consider two aspects: memory consumption and performance.
359
360 [call [cmd ::mysql::seek] [arg handle] [arg row-index]]
361
362 Moves the current position among the rows in the pending result.
363 This may cause [term ::mysql::fetch] and [term ::mysql::map] to re-read rows, or to
364 skip over rows.
365 [nl]
366 Row index 0 is the position just before the first row in the pending result;
367 row index 1 is the position just before the second row, and so
368 on.
369 You may specify a negative row index.
370 Row index -1 is the position just before the last row;
371 row index -2 is the position just before the second last row,
372 and so on.
373 An out-of-bounds row index will cause ::mysql::seek to set the new current
374 position either just before the first row (if the index is too negative),
375 or just after the last row (if the index exceeds the number of rows).
376 This is not an error condition.
377 [nl]
378 ::mysql::seek returns the number of rows that can be read sequentially from
379 the new current position.
380 ::mysql::seek raises a Tcl error if there is no pending result for [arg handle].
381 [nl]
382 Portability note: The functionality of [arg ::mysql::seek] is frequently
383 absent in other Tcl extensions for SQL.
384 That is because MySQL C-API client library ofers own result set caching functionality
385 that lacks another SQL-APIs.
386 That increase the performance because all rows are received at once and the query does
387 not block the server for another clienst , on the other
388 hand you works on the cached data can use a lot of memory and are up to date only in the moment
389 of query but not fetch.
390 [nl]
391
392 [call [cmd ::mysql::col] [arg handle] [arg table-name] [arg option]]
393 [call [cmd ::mysql::col] [arg handle] [arg table-name] [arg optionkist]]
394 [call [cmd ::mysql::col] [arg handle] [opt [arg option]...]]
395
396 Return information about the columns of a table.
397 [arg handle] must be in use.
398 [arg table-name] must be the name of a table; it may be a table name
399 or [arg -current] if there is a pending result.
400 One or more options control what information to return.
401 Each option must be one of the following keywords.
402 [list_begin opt]
403
404 [opt_def name] Return the name of a column.
405
406 [opt_def type]
407 Return the type of a column; one of the strings [emph decimal],
408 [emph tiny], [emph short], [emph long], [emph float], [emph double],
409 [emph null], [emph timestamp], [emph "long long"], [emph int24], [emph date],
410 [emph time], [emph "date time"], [emph year], [emph "new date"], [emph enum],
411 [emph set], [emph "tiny blob"], [emph "medium blob"], [emph "long blob"],
412 [emph blob], [emph "var string"], or [emph string].
413 Note that a column of type [emph char] will return tiny, while they are 
414 represented equally.
415
416 [opt_def length] Return the length of a column in bytes.
417
418 [opt_def table] Return the name of the table in which this column occurs.
419
420 [opt_def non_null] Return the string "1" if the column is non-null; otherwise "0".
421
422 [opt_def prim_key] Return the string "1" if the column is part of the primary key;
423 otherwise "0".
424
425 [opt_def numeric] Return the string "1" if the column is numeric; otherwise "0".
426
427 [opt_def decimals] Return the string "1" if the column is non-null; otherwise "0".
428 [list_end]
429
430 The three forms of this command generate their result in a
431 particular way.
432 [list_begin enum]
433 [enum]
434 If a single option is present the result is a simple list of
435 values; one for each column.
436 [enum]
437 If the options are given in the form of an option list the
438 result is a list of lists.
439 Each sublist corresponds to a column and contains the information
440 specified by the options.
441 [enum]
442 If several options are given, but not in a list, the result is also
443 a list of lists.
444 In this case each sublist corresponds to an option and contains one
445 value for each column.
446 [list_end]
447
448 The following is a sample interactive session containing all forms of
449 the ::mysql::col command and their results.
450 The last command uses the [emph -current] option.
451 It could alternatively specify the table name explicitly.
452 [example_begin]
453 %::mysql::col $db friends name
454 name lname area phone
455 % ::mysql::col $db friends {name type length}
456 {fname char 12} {lname char 20} {area char 5} {phone char 12}
457 % ::mysql::sel $db {select * from friends}
458 % ::mysql::col $db -current name type length
459 {fname lname area phone} {char char char char} {12 20 5 12}]
460 [example_end]
461
462 [call [cmd ::mysql::info] [arg handle] [arg  option]]
463
464 Return various database information depending on the [arg option].
465 The option must be one of the following keywords.
466
467 [list_begin opt]
468 [opt_def info]
469 Return a String with information about last operation.
470 "Records: 3 Duplicates: 0 Warnings: 0" by INSERT or 
471 "Rows matched: 40 Changed: 40 Warnings: 0" by UPDATE statements
472 (read the manual for mysql_info in MySQL C API documentation) 
473
474 [opt_def databases]
475 Return a list of all database names known to the server.
476 The handle must be connected.
477
478 [opt_def dbname]
479 Return the name of the database with which the handle is associated.
480 The handle must be in use.
481
482 [opt_def dbname?]
483 Return the name of the database with which the handle is associated;
484 an empty string if the handle is connected, but not in use.
485
486 [opt_def host]
487 Return the name of the host to which the handle is connected.
488 The handle must be connected.
489
490 [opt_def host]
491 Return the name of the host to which the handle is connected; an empty
492 string if the handle is not valid.
493
494 [opt_def tables]
495 Return a list of all table names in the database with which the handle
496 is associated.
497 The handle must be in use.
498
499 [opt_def serverversion] 
500 Returns the version number of the server as a string.
501
502 [opt_def serverversionid]
503 Returns the version number of the server as an integer.
504
505 [opt_def sqlstate]
506 Returns a string containing the SQLSTATE error code for the last error.
507 The error code consists of five characters. '00000' means ``no error.''
508 The values are specified by ANSI SQL and ODBC.
509
510 Note that not all MySQL errors are yet mapped to SQLSTATE's.
511 The value 'HY000' (general error) is used for unmapped errors. 
512
513 [opt_def state]
514 Returns a character string containing information similar to that provided by the mysqladmin status command.
515 This includes uptime in seconds and the number of running threads, questions, reloads, and open tables.
516
517 [list_end]
518
519 [call [cmd ::mysql::baseinfo] [arg option]]
520
521 return information information that do not need handle.
522 [list_begin opt]
523
524 [opt_def connectparameters]
525 return all supported connecting options
526
527 [opt_def clientversion]
528 return the version of underlying MYSQL C-API library
529 [list_end]
530
531 [call [cmd ::mysql::ping] [arg handle]]
532
533 Checks whether the connection to the server is working. If it has gone down, an automatic reconnection is attempted.
534 [nl]
535 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.
536 [nl]
537 Return True if server is alive
538
539 [call [cmd ::mysql::changeuser] [arg user] [arg password] [opt [arg database]]]
540
541 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.
542 [nl]
543 ::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
544 [nl]
545 if database parameter may be set were is no default database. 
546 [nl]
547 Cause Error if operation is not succesed
548
549 [call [cmd ::mysql::result] [arg handle] [arg option]]
550
551 Return information about the pending result.
552 Note that a result is pending until canceled by a ::mysql::exec command,
553 even if no rows remain to be read.
554 [arg Option] must be one of the following keywords.
555
556 [list_begin opt]
557
558 [opt_def cols]
559 Return the number of columns in the pending result.
560 There must be a pending result.
561
562 [opt_def cols]
563 Return the number of columns in the pending result; an empty string if
564 no result is pending.
565
566 [opt_def current]
567 Return the current position in the pending result; a non-negative integer.
568 This value can be used as [arg row-index] in the ::mysql::seek command.
569 An error is raised if there is no pending result.
570
571 [opt_def current?]
572 As above, but returns an empty string if there is no pending result.
573
574 [opt_def rows]
575 Return the number of rows that can be read sequentially from the
576 current position in the pending result.
577 There must be a pending result.
578
579 [opt_def rows]
580 Return the number of rows that can be read sequentially from the
581 current position in the pending result; an empty string if no result
582 is pending.
583 [nl]
584 [lb]::mysql::result $db current[rb] + [lb]::mysql::result $db rows[rb]
585 always equals the total number of rows in the pending result.
586 [list_end]
587
588 [call [cmd ::mysql::state] [arg handle] [opt [arg -numeric]]]
589
590 Return the state of a handle as a string or in numeric form.
591 There is no requirement on [arg handle]; it may be any string.
592 The return value is one of the following strings, or the corresponding
593 numeric value if [arg -numeric] is specified.
594 The states form a progression where each state builds on the previous.
595 [list_begin opt]
596
597 [opt_def "NOT_A_HANDLE (0)"]
598 The string supplied for [arg handle] is not a mysqltcl handle at all.
599
600 [opt_def "UNCONNECTED (1)"]
601 The string supplied for [arg handle] is one of the possible mysqltcl
602 handles, but it is not valid to any server.
603
604 [opt_def "CONNECTED (2)"]
605 The handle is connected to a server, but not associated with a database.
606
607 [opt_def "IN_USE (3)"]
608 The handle is connected and associated with a database, but there is
609 no pending result.
610
611 [opt_def "RESULT_PENDING (4)"]
612 The handle is connected, associated with a database, and there is a
613 pending result.
614 [list_end]
615
616 [call [cmd ::mysql::close] [opt [arg handle]]]
617
618 Closes the server connection associated with [arg handle], causing it
619 to go back to the unconnected state.
620 Closes all connections if [arg handle] is omitted.
621 Returns an empty string.
622 ::mysql::close raises a Tcl error if a handle is specified which is not
623 valid.
624
625 [call [cmd ::mysql::insertid] [arg handle]]
626
627 Returns the auto increment id of the last INSERT statement.
628
629 [call [cmd ::mysql::escape] [opt [arg handle]] [arg string]]
630
631 Returns the content of [arg string], with all special characters escaped,
632 so that it is suitable for use in an SQL statement. This is simpler (faster)
633 than using a general [emph regexp] or string map.
634 If handle is specified C-API function mysql_real_escape_string is used.
635 This is the recommended usage because in this case current character set is respected.
636
637 [call [cmd ::mysql::autocommit] [arg handle] [arg boolean]]
638 Sets autocommit mode on if mode is 1, off if mode is 0.
639
640 [call [cmd ::mysql::commit] [arg handle]]
641 Commits the current transaction.
642
643 [call [cmd ::mysql::rollback] [arg handle]]
644 Rollback the current transaction.
645
646 [call [cmd ::mysql::nextresult] [arg handle]]
647 If more query results exist, mysql::nextresult() reads the next query results and returns the status back to application.
648 returns -1 if no result or number of rows in the result set.
649
650 [call [cmd ::mysql::moreresult] [arg handle]]
651 Returns true if more results exist from the currently executed query, and the application must call mysql::result to fetch the results.
652
653 [call [cmd ::mysql::warningcount] [arg handle]]
654 Returns the number of warnings generated during execution of the previous SQL statement.
655
656
657 [call [cmd ::mysql::isnull] [arg value]]
658 Null handling is a known problem with Tcl, especially with DB interaction.
659 The mysql "varchar" type has two valid blank values, NULL and an empty
660 string. This is where the problem arises; Tcl is not able to differentiate
661 between the two because of the way it handles strings.
662 Mysql has new internal Tcl type for null that string representation is stored
663 in global array mysqltcl(nullvalue) and as default empty string.
664 mysql::isnull can be used for safe check for null value.
665 Warning mysql::isnull works only reliable if there are no type conversation on
666 returned rows.
667 Consider row is always Tcl list even when there are only one column in the row.
668 [example_begin]
669 set row [lb]::mysql::next $handle[rb]
670 if {[lb]mysql::isnull [lb]lindex $row 1[rb]]} {
671    puts "2. column of $row is null"
672 }
673 if {[lb]mysql::isnull $row[rb]} {
674    puts "this does not work, because of type conversation list to string"
675 }
676 [example_end]
677
678 [call [cmd ::mysql::newnull]]
679 create new null object. It can be used to simulate returned row contents.
680
681 [call [cmd ::mysql::setserveroption] [arg handle] [arg option]]
682 there are only 2 options now: -multi_statment_on and -multi_statment_off
683
684 [call [cmd ::mysql::shutdown] [arg handle]]
685 Asks the database server to shut down. The connected user must have SHUTDOWN privileges. 
686
687 [call [cmd ::mysql::encoding] [arg handle] [opt encoding]]
688 Ask or change a encoding of connection.
689 There are special encoding "binary" for binary data transfers.
690
691 [list_end]
692
693 [section "STATUS INFORMATION"]
694 Mysqltcl creates and maintains a Tcl global array to provide status
695 information. 
696 Its name is [emph mysqlstatus].
697 .P
698 Mysqlstatus elements:
699 [list_begin definitions]
700 [lst_item code]
701
702 A numeric conflict code set after every mysqltcl command.
703 Zero means no conflict; non-zero means some kind of conflict.
704 All conflicts also generate a Tcl error.
705 [nl]
706 All MySQL server conflicts set mysqlstatus(code) to the numeric
707 code of the MySQL error.
708 [nl]
709 Any other conflict sets mysqlstatus(code) to -1.
710
711 [lst_item command]
712 The last failing mysqltcl command.
713 Not updated for successful commands.
714
715 [lst_item message]
716 Message string for the last conflict detected.
717 The same string is returned as the result of the failing mysqltcl
718 command.
719 Not updated for successful commands.
720
721 [lst_item nullvalue]
722 The string to use in query results to represent the SQL null value.
723 The empty string is used initially.
724 You may set it to another value.
725 [list_end]
726
727 [section "Backward compatibility"]
728 Up from version 3.0 all mysql commands are declared in ::mysql namespace.
729 All names for example mysqlconnect are also aviable but deprecated.
730 All old commands have the name pattern mysql{name} and the most of them are now mysql::{name}.
731 The exception is mysqlnext, which  was renamed to mysql::fetch.
732
733 [section "BUGS & POSSIBLE MISFEATURES"]
734
735 Deleting any of the mysqltcl commands closes all connections.
736
737 [section AUTHORS]
738
739 [list_begin bullet]
740 [bullet]
741 Tobias Ritzau
742 [bullet]
743 Paolo Brutti
744 [bullet]
745 Artur Trzewik (mail@xdobry.de) - active maintainer
746
747 [list_end]
748
749 MySQLTcl is derived from a patch of msql by Hakan Soderstrom, Soderstrom Programvaruverkstad,
750 S-12242 Enskede, Sweden.
751 msql is derived from Sybtcl by Tom Poindexter.
752 There are many contributors and bug reporter that are not mentioned.
753 If you have contributed to mysqltcl and wants to be on the list contact Artur Trzewik.
754 [manpage_end]