Imported Upstream version 3.05
[sven/mysqltcl.git] / doc / mysqltcl.n
1 '\"
2 '\" Generated from file 'mysqltcl.man' by tcllib/doctools with format 'nroff'
3 '\"
4 '\" -*- tcl -*- mysqltcl manpage
5 '\" The definitions below are for supplemental macros used in Tcl/Tk
6 '\" manual entries.
7 '\"
8 '\" .AP type name in/out ?indent?
9 '\"     Start paragraph describing an argument to a library procedure.
10 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
11 '\"     or "in/out" to describe whether procedure reads or modifies arg,
12 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
13 '\"     needed;  use .AS below instead)
14 '\"
15 '\" .AS ?type? ?name?
16 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
17 '\"     name are examples of largest possible arguments that will be passed
18 '\"     to .AP later.  If args are omitted, default tab stops are used.
19 '\"
20 '\" .BS
21 '\"     Start box enclosure.  From here until next .BE, everything will be
22 '\"     enclosed in one large box.
23 '\"
24 '\" .BE
25 '\"     End of box enclosure.
26 '\"
27 '\" .CS
28 '\"     Begin code excerpt.
29 '\"
30 '\" .CE
31 '\"     End code excerpt.
32 '\"
33 '\" .VS ?version? ?br?
34 '\"     Begin vertical sidebar, for use in marking newly-changed parts
35 '\"     of man pages.  The first argument is ignored and used for recording
36 '\"     the version when the .VS was added, so that the sidebars can be
37 '\"     found and removed when they reach a certain age.  If another argument
38 '\"     is present, then a line break is forced before starting the sidebar.
39 '\"
40 '\" .VE
41 '\"     End of vertical sidebar.
42 '\"
43 '\" .DS
44 '\"     Begin an indented unfilled display.
45 '\"
46 '\" .DE
47 '\"     End of indented unfilled display.
48 '\"
49 '\" .SO
50 '\"     Start of list of standard options for a Tk widget.  The
51 '\"     options follow on successive lines, in four columns separated
52 '\"     by tabs.
53 '\"
54 '\" .SE
55 '\"     End of list of standard options for a Tk widget.
56 '\"
57 '\" .OP cmdName dbName dbClass
58 '\"     Start of description of a specific option.  cmdName gives the
59 '\"     option's name as specified in the class command, dbName gives
60 '\"     the option's name in the option database, and dbClass gives
61 '\"     the option's class in the option database.
62 '\"
63 '\" .UL arg1 arg2
64 '\"     Print arg1 underlined, then print arg2 normally.
65 '\"
66 '\" RCS: @(#) $Id$
67 '\"
68 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
69 .if t .wh -1.3i ^B
70 .nr ^l \n(.l
71 .ad b
72 '\"     # Start an argument description
73 .de AP
74 .ie !"\\$4"" .TP \\$4
75 .el \{\
76 .   ie !"\\$2"" .TP \\n()Cu
77 .   el          .TP 15
78 .\}
79 .ta \\n()Au \\n()Bu
80 .ie !"\\$3"" \{\
81 \&\\$1  \\fI\\$2\\fP    (\\$3)
82 .\".b
83 .\}
84 .el \{\
85 .br
86 .ie !"\\$2"" \{\
87 \&\\$1  \\fI\\$2\\fP
88 .\}
89 .el \{\
90 \&\\fI\\$1\\fP
91 .\}
92 .\}
93 ..
94 '\"     # define tabbing values for .AP
95 .de AS
96 .nr )A 10n
97 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
98 .nr )B \\n()Au+15n
99 .\"
100 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
101 .nr )C \\n()Bu+\\w'(in/out)'u+2n
102 ..
103 .AS Tcl_Interp Tcl_CreateInterp in/out
104 '\"     # BS - start boxed text
105 '\"     # ^y = starting y location
106 '\"     # ^b = 1
107 .de BS
108 .br
109 .mk ^y
110 .nr ^b 1u
111 .if n .nf
112 .if n .ti 0
113 .if n \l'\\n(.lu\(ul'
114 .if n .fi
115 ..
116 '\"     # BE - end boxed text (draw box now)
117 .de BE
118 .nf
119 .ti 0
120 .mk ^t
121 .ie n \l'\\n(^lu\(ul'
122 .el \{\
123 .\"     Draw four-sided box normally, but don't draw top of
124 .\"     box if the box started on an earlier page.
125 .ie !\\n(^b-1 \{\
126 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
127 .\}
128 .el \}\
129 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
130 .\}
131 .\}
132 .fi
133 .br
134 .nr ^b 0
135 ..
136 '\"     # VS - start vertical sidebar
137 '\"     # ^Y = starting y location
138 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
139 .de VS
140 .if !"\\$2"" .br
141 .mk ^Y
142 .ie n 'mc \s12\(br\s0
143 .el .nr ^v 1u
144 ..
145 '\"     # VE - end of vertical sidebar
146 .de VE
147 .ie n 'mc
148 .el \{\
149 .ev 2
150 .nf
151 .ti 0
152 .mk ^t
153 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
154 .sp -1
155 .fi
156 .ev
157 .\}
158 .nr ^v 0
159 ..
160 '\"     # Special macro to handle page bottom:  finish off current
161 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
162 '\"     # page bottom macro.
163 .de ^B
164 .ev 2
165 'ti 0
166 'nf
167 .mk ^t
168 .if \\n(^b \{\
169 .\"     Draw three-sided box if this is the box's first page,
170 .\"     draw two sides but no top otherwise.
171 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
172 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
173 .\}
174 .if \\n(^v \{\
175 .nr ^x \\n(^tu+1v-\\n(^Yu
176 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
177 .\}
178 .bp
179 'fi
180 .ev
181 .if \\n(^b \{\
182 .mk ^y
183 .nr ^b 2
184 .\}
185 .if \\n(^v \{\
186 .mk ^Y
187 .\}
188 ..
189 '\"     # DS - begin display
190 .de DS
191 .RS
192 .nf
193 .sp
194 ..
195 '\"     # DE - end display
196 .de DE
197 .fi
198 .RE
199 .sp
200 ..
201 '\"     # SO - start of list of standard options
202 .de SO
203 .SH "STANDARD OPTIONS"
204 .LP
205 .nf
206 .ta 4c 8c 12c
207 .ft B
208 ..
209 '\"     # SE - end of list of standard options
210 .de SE
211 .fi
212 .ft R
213 .LP
214 See the \\fBoptions\\fR manual entry for details on the standard options.
215 ..
216 '\"     # OP - start of full description for a single option
217 .de OP
218 .LP
219 .nf
220 .ta 4c
221 Command-Line Name:      \\fB\\$1\\fR
222 Database Name:  \\fB\\$2\\fR
223 Database Class: \\fB\\$3\\fR
224 .fi
225 .IP
226 ..
227 '\"     # CS - begin code excerpt
228 .de CS
229 .RS
230 .nf
231 .ta .25i .5i .75i 1i
232 ..
233 '\"     # CE - end code excerpt
234 .de CE
235 .fi
236 .RE
237 ..
238 .de UL
239 \\$1\l'|0\(ul'\\$2
240 ..
241 .TH "mysqltcl" n 3.0  ""
242 .BS
243 .SH "NAME"
244 mysqltcl \- MySQL server access commands for Tcl
245 '\"
246 '\" Copyright (c) 1994, 1995 Hakan Soderstrom and Tom Poindexter
247 '\" Permission to use, copy, modify, distribute, and sell this software
248 '\" and its documentation for any purpose is hereby granted without fee,
249 '\" provided that the above copyright notice and this permission notice
250 '\" appear in all copies of the software and related documentation.
251 '\"
252 '\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
253 '\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
254 '\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
255 '\"
256 '\" IN NO EVENT SHALL HAKAN SODERSTROM OR SODERSTROM PROGRAMVARUVERKSTAD
257 '\" AB BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL
258 '\" DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
259 '\" OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY
260 '\" OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN
261 '\" CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
262 '\"
263 '\" $Id: mysqltcl.n,v 1.1.1.1 2002/02/15 18:21:17 artur Exp $
264 '\"
265 '\" Updates by Tobias Ritzau 1998-03-18
266 '\" Replaced all mysql by mysql
267 '\" Updated the mysqlconnect documentation
268 '\"
269 '\" 1998-07-06
270 '\" Changed some mysql back to msql
271 '\" Updaated the name and introduction
272 '\" Updated the mysqlcol documentation
273 '\"
274 '\" Copyright (c) 1998 Tobias Ritzau
275 '\"
276 '\" Updates by Artur Trzewik 2002-11-31
277 '\" for mysqltcl2.1 (mysql::query mysq::endquery)
278 '\"
279 '\" Updates by Artur Trzewik 2002-11-31
280 '\" for mysqltcl3.0
281 '\"
282 .SH "SYNOPSIS"
283 package require \fBTcl  8.4\fR
284 .sp
285 package require \fBmysqltcl  3.0\fR
286 .sp
287 \fB::mysql::connect\fR ?\fIoption value\fR...?
288 .sp
289 \fB::mysql::use\fR \fIhandle\fR \fIdatabase\fR
290 .sp
291 \fB::mysql::sel\fR \fIhandle\fR \fIsql-statement\fR ?\fI-list|-flatlist\fR?
292 .sp
293 \fB::mysql::fetch\fR \fIhandle\fR
294 .sp
295 \fB::mysql::exec\fR \fIhandle\fR \fIsql-statement\fR
296 .sp
297 \fB::mysql::query\fR \fIhandle\fR \fIsql-select-statement\fR
298 .sp
299 \fB::mysql::endquery\fR \fIquery-handle\fR
300 .sp
301 \fB::mysql::map\fR \fIhandle\fR \fIbinding-list\fR \fIscript\fR
302 .sp
303 \fB::mysql::receive\fR \fIhandle\fR \fIsql-statment\fR \fIbinding-list\fR \fIscript\fR
304 .sp
305 \fB::mysql::seek\fR \fIhandle\fR \fIrow-index\fR
306 .sp
307 \fB::mysql::col\fR \fIhandle\fR \fItable-name\fR \fIoption\fR
308 .sp
309 \fB::mysql::col\fR \fIhandle\fR \fItable-name\fR \fIoptionkist\fR
310 .sp
311 \fB::mysql::col\fR \fIhandle\fR ?\fIoption\fR...?
312 .sp
313 \fB::mysql::info\fR \fIhandle\fR \fIoption\fR
314 .sp
315 \fB::mysql::baseinfo\fR \fIoption\fR
316 .sp
317 \fB::mysql::ping\fR \fIhandle\fR
318 .sp
319 \fB::mysql::changeuser\fR \fIuser\fR \fIpassword\fR ?\fIdatabase\fR?
320 .sp
321 \fB::mysql::result\fR \fIhandle\fR \fIoption\fR
322 .sp
323 \fB::mysql::state\fR \fIhandle\fR ?\fI-numeric\fR?
324 .sp
325 \fB::mysql::close\fR ?\fIhandle\fR?
326 .sp
327 \fB::mysql::insertid\fR \fIhandle\fR
328 .sp
329 \fB::mysql::escape\fR ?\fIhandle\fR? \fIstring\fR
330 .sp
331 \fB::mysql::autocommit\fR \fIhandle\fR \fIboolean\fR
332 .sp
333 \fB::mysql::commit\fR \fIhandle\fR
334 .sp
335 \fB::mysql::rollback\fR \fIhandle\fR
336 .sp
337 \fB::mysql::nextresult\fR \fIhandle\fR
338 .sp
339 \fB::mysql::moreresult\fR \fIhandle\fR
340 .sp
341 \fB::mysql::warningcount\fR \fIhandle\fR
342 .sp
343 \fB::mysql::isnull\fR \fIvalue\fR
344 .sp
345 \fB::mysql::newnull\fR
346 .sp
347 \fB::mysql::setserveroption\fR \fIhandle\fR \fIoption\fR
348 .sp
349 \fB::mysql::shutdown\fR \fIhandle\fR
350 .sp
351 \fB::mysql::encoding\fR \fIhandle\fR ?encoding?
352 .sp
353 .BE
354 .SH "DESCRIPTION"
355 MySQLTcl is a collection of Tcl commands and a Tcl global array that
356 provide access to MySQL database servers.
357 .PP
358 MySQLTcl is nothing more than a patched version of a patched version
359 of Hakan Soderstrom's patch of Tom Poindexter's Sybtcl.
360 .PP
361 Mysqltcl is binary Tcl library (extension) written in C language that use direkt
362 official MySQL C-API. Almost all Tcl commands correspond to MySQL C-API functions.
363 For detail documentation see official MySQL C-API manual.
364 .SH "MYSQLTCL COMMANDS"
365 .TP
366 \fB::mysql::connect\fR ?\fIoption value\fR...?
367 Connect to a MySQL server.
368 A handle is returned which should be used in other mysqltcl
369 commands using this connection.
370 ::mysql::connect raises a Tcl error if the connection fails.
371 ::mysql::connect read first the options from my.cnf file group mysqltcl.
372 See MySQL documentation chapter "options files".
373 Possible connection options are:
374 .RS
375 .TP
376 \fB-host\fR \fIhostname\fR
377 The host on which the server is located. The local host is used by default.
378 .TP
379 \fB-user\fR \fIuser\fR
380 The user whose name is used for the connection.
381 The current Unix user-name is used by default.
382 .TP
383 \fB-password\fR \fIpassword\fR
384 The password that must be used for the connection.
385 If it is not present, the connection is possible only for users with
386 no password on the server.
387 .TP
388 \fB-db\fR \fIdb\fR
389 If this option is present, \fIdb\fR is used as current database, with no need
390 for a call to \fImysql::use\fR.
391 .TP
392 \fB-port\fR \fIport\fR
393 The port number for the TCP/IP connection, if it's different from the default.
394 .TP
395 \fB-socket\fR \fIsocket\fR
396 The socket or named pipe for the connection.
397 .TP
398 \fB-encoding\fR \fIencodingname\fR
399 The option works similar to -encoding option in fconfigure. It support also
400 special encoding name binary. By option -binary no converting will be done be reading or writing to/from MySQL.
401 If option is not set the system encoding (see utf-8) is used.
402 Please test all input and outputs with another program to check that all
403 is the way you expect it. If option binary is not used the system procedures
404 Tcl_ExternalToUtfDString (writing) and Tcl_ExternalToUtf (reading) will be used
405 by option binary the function Tcl_GetByteArrayFromObj and Tcl_NewByteArrayObj are used.
406 If you want to manipulate binary date use -encoding binary. By handling textes set your
407 special encoding that you want to use in your database. Consider what another system access the
408 database and what encoding they expect. It can useful
409 to use -encoding utf-8. That is standard encoding in some linux distributions and newer systems.
410 .TP
411 \fB-compress\fR \fIboolean\fR
412 Use compression protocol. Default is false
413 .TP
414 \fB-odbc\fR \fIboolean\fR
415 The client is an ODBC client. This changes mysqld to be more ODBC-friendly. Default is false
416 .TP
417 \fB-noschema\fR \fIboolean\fR
418 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
419 .TP
420 \fB-multistatement\fR \fIboolean\fR
421 Tell the server that the client may send multiple-row-queries (separated by `;').
422 If this flag is not set, multiple-row-queries are disabled. Default is false.
423 .TP
424 \fB-multiresult\fR \fIboolean\fR
425 Tell the server that the client can handle multiple-result sets from multi-queries or stored procedures.
426 This is automatically set if CLIENT_MULTI_STATEMENTS is set.
427 .TP
428 \fB-localfiles\fR \fIboolean\fR
429 Enable LOAD DATA LOCAL handling. Default is false.
430 .TP
431 \fB-foundrows\fR \fIboolean\fR
432 Return the number of found (matched) rows, not the number of affected rows.
433 Default is false.
434 .TP
435 \fB-interactive\fR \fIboolean\fR
436 Allow interactive_timeout seconds (instead of wait_timeout seconds) of inactivity before closing the connection.
437 The client's session wait_timeout variable will be set to the value of the session interactive_timeout variable.
438 Default is false.
439 .TP
440 \fB-ssl\fR \fIboolean\fR
441 Switch to SSL after handshake. Default is  false
442 .TP
443 \fB-sslkey\fR \fIstring\fR
444 is the pathname to the key file.
445 Used if -ssl is true
446 .TP
447 \fB-sslcert\fR \fIstring\fR
448 is the pathname to the certificate file.
449 Used if -ssl is true
450 .TP
451 \fB-sslca\fR \fIstring\fR
452 is the pathname to the certificate authority file.
453 Used if -ssl is true
454 .TP
455 \fB-sslcapath\fR \fIstring\fR
456 is the pathname to a directory that contains trusted SSL CA certificates in pem format.
457 Used if -ssl is true
458 .TP
459 \fB-sslcipher\fR \fIstring\fR
460 is a list of allowable ciphers to use for SSL encryption.
461 Used if -ssl is true
462 .RE
463 .TP
464 \fB::mysql::use\fR \fIhandle\fR \fIdatabase\fR
465 Associate a connected handle with a particular database.
466 \fIhandle\fR must be a valid handle previously obtained from ::mysql::connect.
467 mysql::use raises a Tcl error if the handle is not valid or
468 if the database name specified could not be used.
469 .sp
470 Consider you can use mysqltcl without to specify the database, in this case
471 you must use explizit schema notation to specify the table in sql.
472 .nf
473 ::mysql::sel $handle {select * from uni.student}
474 .fi
475 with option connection \fI-noschema\fR you can prohibit such syntax.
476 .TP
477 \fB::mysql::sel\fR \fIhandle\fR \fIsql-statement\fR ?\fI-list|-flatlist\fR?
478 Send \fIsql-statement\fR to the server.
479 .sp
480 If \fIsql-statement\fR is a SELECT statement and no \fI-list\fR or
481 \fI-flatlist\fR option is specified, the command returns the
482 number of rows returned as the result of the query.
483 The rows can be obtained by the \fI::mysql::fetch\fR and/or the
484 \fI::mysql::map\fR commands.
485 The resulting rows are called the \fIpending result\fR.
486 .sp
487 If \fIsql-statement\fR is a SELECT statement and \fI-list\fR or \fI-flatlist\fR
488 is specified, the command returns the full list of rows returned as
489 the result of the query in one of two possible formats:
490 .RS
491 .TP
492 \fB-list\fR
493 generates a list of lists, in which each element is a row of the result.
494 .TP
495 \fB-flatlist\fR
496 generates the concatenation of all rows in a single list, which
497 is useful for scanning with a single \fIforeach\fR.
498 .RE
499 Example:
500 .nf
501 % ::mysql::sel $db "SELECT ID, NAME FROM FRIENDS" -list
502 {1 Joe} {2 Phil} {3 John}
503 % ::mysql::sel $db "SELECT ID, NAME FROM FRIENDS" -flatlist
504 {1 Joe 2 Phil 3 John}
505 .fi
506 Note that both list syntaxes are faster than something like
507 .nf
508 % ::mysql::sel $db "SELECT ID, NAME FROM FRIENDS"
509 % ::mysql::map $db {id name} {lappend result $id $name}
510 % set $result
511 {1 Joe 2 Phil 3 John}
512 .fi
513 If \fIsql-statement\fR is a valid MySQL statement, but not a SELECT
514 statement, the command returns -1 after executing the statement, or an empty
515 string if \fI-list\fR or \fI-flatlist\fR is specified.
516 There is no pending result in this case.
517 .sp
518 In any case ::mysql::sel implicitly cancels any previous result still
519 pending for the handle.
520 .TP
521 \fB::mysql::fetch\fR \fIhandle\fR
522 Returns the next row from result set as Tcl list.
523 mysql::fetch raises a Tcl error if there is no pending result for \fIhandle\fR.
524 mysql::fetch was former named mysqlnext.
525 .TP
526 \fB::mysql::exec\fR \fIhandle\fR \fIsql-statement\fR
527 Send \fIsql-statement\fR, a MySQL non-SELECT statement, to the server.
528 The \fIhandle\fR must be in use (through ::mysql::connect and ::mysql::use).
529 .sp
530 ::mysql::exec implicitly cancels any previous result pending for the handle.
531 .sp
532 If \fIsql-statement\fR is a valid MySQL SELECT statement, the statement
533 is executed, but the result is discarded.
534 No Tcl error is generated.
535 This amounts to a (potentially costly) no-op.
536 Use the ::mysql::sel command for SELECT statements.
537 .sp
538 ::mysql::exec returns the number of affected rows (DELETE, UPDATE).
539 In case of multiple statement ::mysql::exec returns a list of number of affected rows.
540 .sp
541 .TP
542 \fB::mysql::query\fR \fIhandle\fR \fIsql-select-statement\fR
543 Send \fIsql-select-statement\fR to the server.
544 .sp
545 \fImysql::query\fR allow to send multiple nested queries on one handle (without need to build
546 new handle or caching results).
547 mysql::query return a query handle that can be used as handle in commands as (mysql::fetch,
548 ::mysql::map, mysql::seek, mysql::col, mysql::result).
549 After result proceeding all query must be
550 freed with \fI::mysql::endquery query-hanlde\fR command.
551 .sp
552 Example:
553 .nf
554 set query1 [::mysql::query $db {SELECT ID, NAME FROM FRIENDS}\\]
555 while {[set row [::mysql::fetch $query1]]!=""} {
556     set id [lindex $row 0]
557     set query2 [::mysql::query $db "SELECT ADDRESS FROM ADDRESS WHERE FRIENDID=$ID"]
558     ::mysql::map $query2 address { puts "address = $address" }
559     ::mysql::endquery $query2
560 }
561 ::mysql::endquery $query1
562 .fi
563 In most cases one should use sql-joins and avoid nested queries.
564 SQL-sever can optimize such queries.
565 But in some applications (GUI-Forms) where the results are used long time the inner
566 query is not known before.
567 .TP
568 \fB::mysql::endquery\fR \fIquery-handle\fR
569 free result memory after \fI::mysql::query\fR command.
570 You must invoke ::mysql::endquery after each mysqlquery to not cause memory leaks. See mysqlquery command.
571 .sp
572 Using \fI::mysql::endquery\fR on db-handle will free also memory (pending result) after \fI::mysql::sel\fR command.
573 .sp
574 .TP
575 \fB::mysql::map\fR \fIhandle\fR \fIbinding-list\fR \fIscript\fR
576 Iterate a script over the rows of the pending result.
577 ::mysql::map may consume all rows or only some of the rows of the pending
578 result.
579 Any remaining rows may be obtained by further ::mysql::fetch or ::mysql::map
580 commands.
581 .sp
582 \fIhandle\fR must be a handle with a pending result from a previous
583 ::mysql::sel command.
584 \fIbinding-list\fR must be a list of one or more variable names.
585 \fIscript\fR must be a Tcl script.
586 It may be empty, but usually it contains one or more commands.
587 .sp
588 ::mysql::map processes one row at a time from the pending result.
589 For each row the column values are bound to the variables in the
590 binding list, then the script is executed.
591 Binding is strictly positional.
592 The first variable in the binding list is bound to the first column of
593 the row, and so on.
594 The variables are created in the current context (if they do not
595 already exist).
596 A variable name begining with a hyphen is not bound; it serves as a
597 placeholder in the binding list.
598 If there are more columns than variables the extra columns are
599 ignored.
600 .sp
601 The ::mysql::map command is similar to an ordinary \fIforeach\fR.
602 A \fIforeach\fR iterates over the elements of a list, ::mysql::map
603 iterates over the rows of a pending result.
604 In both cases iteration is affected by \fIbreak\fR and \fIcontinue\fR
605 Tcl commands.
606 The binding list variables retain their last values after the command
607 has completed.
608 .sp
609 A simple example follows.
610 Assume $db is a handle in use.
611 .nf
612 ::mysql::sel $db {
613     select lname, fname, area, phone from friends order by lname, fname
614 }
615 ::mysql::map $db {ln fn - phone} {
616    if {$phone == {}} continue
617    puts [format "%16s %-8s %s" $ln $fn $phone]
618 }
619 .fi
620 The ::mysql::sel command gets and sorts all rows from table friends.
621 The ::mysql::map command is used to format and print the result in a way
622 suitable for a phone list.
623 For demonstration purposes one of the columns (area) is not used.
624 The script begins by skipping over rows which have no phone number.
625 The second command in the script formats and prints values from the row.
626 .sp
627 ::mysql::map raises a Tcl error if there is no pending result for
628 \fIhandle\fR, or if \fIbinding-list\fR contains more variables than
629 there are columns in the pending result.
630 .sp
631 .TP
632 \fB::mysql::receive\fR \fIhandle\fR \fIsql-statment\fR \fIbinding-list\fR \fIscript\fR
633 This command works the same way as the command mysqtclmap but
634 it do not need leading ::mysql::sel command.
635 The main difference is internal using of MySQL client library.
636 This command use mysql_use_result from C-API that do not
637 store result on client but try to receive the rows directly
638 from server.
639 There is also no client cache.
640 This command can be faster as using of ::mysql::sel and by
641 very big resultset will not overload client machine.
642 The scipt should process the result immadiatly because
643 it can block table (or tables) for another clients.
644 If performance matter please test all alternatives separatly.
645 You must consider two aspects: memory consumption and performance.
646 .TP
647 \fB::mysql::seek\fR \fIhandle\fR \fIrow-index\fR
648 Moves the current position among the rows in the pending result.
649 This may cause \fI::mysql::fetch\fR and \fI::mysql::map\fR to re-read rows, or to
650 skip over rows.
651 .sp
652 Row index 0 is the position just before the first row in the pending result;
653 row index 1 is the position just before the second row, and so
654 on.
655 You may specify a negative row index.
656 Row index -1 is the position just before the last row;
657 row index -2 is the position just before the second last row,
658 and so on.
659 An out-of-bounds row index will cause ::mysql::seek to set the new current
660 position either just before the first row (if the index is too negative),
661 or just after the last row (if the index exceeds the number of rows).
662 This is not an error condition.
663 .sp
664 ::mysql::seek returns the number of rows that can be read sequentially from
665 the new current position.
666 ::mysql::seek raises a Tcl error if there is no pending result for \fIhandle\fR.
667 .sp
668 Portability note: The functionality of \fI::mysql::seek\fR is frequently
669 absent in other Tcl extensions for SQL.
670 That is because MySQL C-API client library ofers own result set caching functionality
671 that lacks another SQL-APIs.
672 That increase the performance because all rows are received at once and the query does
673 not block the server for another clienst , on the other
674 hand you works on the cached data can use a lot of memory and are up to date only in the moment
675 of query but not fetch.
676 .sp
677 .TP
678 \fB::mysql::col\fR \fIhandle\fR \fItable-name\fR \fIoption\fR
679 .TP
680 \fB::mysql::col\fR \fIhandle\fR \fItable-name\fR \fIoptionkist\fR
681 .TP
682 \fB::mysql::col\fR \fIhandle\fR ?\fIoption\fR...?
683 Return information about the columns of a table.
684 \fIhandle\fR must be in use.
685 \fItable-name\fR must be the name of a table; it may be a table name
686 or \fI-current\fR if there is a pending result.
687 One or more options control what information to return.
688 Each option must be one of the following keywords.
689 .RS
690 .TP
691 \fBname\fR Return the name of a column.
692 .TP
693 \fBtype\fR
694 Return the type of a column; one of the strings \fIdecimal\fR,
695 \fItiny\fR, \fIshort\fR, \fIlong\fR, \fIfloat\fR, \fIdouble\fR,
696 \fInull\fR, \fItimestamp\fR, \fIlong long\fR, \fIint24\fR, \fIdate\fR,
697 \fItime\fR, \fIdate time\fR, \fIyear\fR, \fInew date\fR, \fIenum\fR,
698 \fIset\fR, \fItiny blob\fR, \fImedium blob\fR, \fIlong blob\fR,
699 \fIblob\fR, \fIvar string\fR, or \fIstring\fR.
700 Note that a column of type \fIchar\fR will return tiny, while they are
701 represented equally.
702 .TP
703 \fBlength\fR Return the length of a column in bytes.
704 .TP
705 \fBtable\fR Return the name of the table in which this column occurs.
706 .TP
707 \fBnon_null\fR Return the string "1" if the column is non-null; otherwise "0".
708 .TP
709 \fBprim_key\fR Return the string "1" if the column is part of the primary key;
710 otherwise "0".
711 .TP
712 \fBnumeric\fR Return the string "1" if the column is numeric; otherwise "0".
713 .TP
714 \fBdecimals\fR Return the string "1" if the column is non-null; otherwise "0".
715 .RE
716 The three forms of this command generate their result in a
717 particular way.
718 .RS
719 .IP [1]
720 If a single option is present the result is a simple list of
721 values; one for each column.
722 .IP [2]
723 If the options are given in the form of an option list the
724 result is a list of lists.
725 Each sublist corresponds to a column and contains the information
726 specified by the options.
727 .IP [3]
728 If several options are given, but not in a list, the result is also
729 a list of lists.
730 In this case each sublist corresponds to an option and contains one
731 value for each column.
732 .RE
733 The following is a sample interactive session containing all forms of
734 the ::mysql::col command and their results.
735 The last command uses the \fI-current\fR option.
736 It could alternatively specify the table name explicitly.
737 .nf
738 %::mysql::col $db friends name
739 name lname area phone
740 % ::mysql::col $db friends {name type length}
741 {fname char 12} {lname char 20} {area char 5} {phone char 12}
742 % ::mysql::sel $db {select * from friends}
743 % ::mysql::col $db -current name type length
744 {fname lname area phone} {char char char char} {12 20 5 12}]
745 .fi
746 .TP
747 \fB::mysql::info\fR \fIhandle\fR \fIoption\fR
748 Return various database information depending on the \fIoption\fR.
749 The option must be one of the following keywords.
750 .RS
751 .TP
752 \fBinfo\fR
753 Return a String with information about last operation.
754 "Records: 3 Duplicates: 0 Warnings: 0" by INSERT or
755 "Rows matched: 40 Changed: 40 Warnings: 0" by UPDATE statements
756 (read the manual for mysql_info in MySQL C API documentation)
757 .TP
758 \fBdatabases\fR
759 Return a list of all database names known to the server.
760 The handle must be connected.
761 .TP
762 \fBdbname\fR
763 Return the name of the database with which the handle is associated.
764 The handle must be in use.
765 .TP
766 \fBdbname?\fR
767 Return the name of the database with which the handle is associated;
768 an empty string if the handle is connected, but not in use.
769 .TP
770 \fBhost\fR
771 Return the name of the host to which the handle is connected.
772 The handle must be connected.
773 .TP
774 \fBhost\fR
775 Return the name of the host to which the handle is connected; an empty
776 string if the handle is not valid.
777 .TP
778 \fBtables\fR
779 Return a list of all table names in the database with which the handle
780 is associated.
781 The handle must be in use.
782 .TP
783 \fBserverversion\fR
784 Returns the version number of the server as a string.
785 .TP
786 \fBserverversionid\fR
787 Returns the version number of the server as an integer.
788 .TP
789 \fBsqlstate\fR
790 Returns a string containing the SQLSTATE error code for the last error.
791 The error code consists of five characters. '00000' means ``no error.''
792 The values are specified by ANSI SQL and ODBC.
793 Note that not all MySQL errors are yet mapped to SQLSTATE's.
794 The value 'HY000' (general error) is used for unmapped errors.
795 .TP
796 \fBstate\fR
797 Returns a character string containing information similar to that provided by the mysqladmin status command.
798 This includes uptime in seconds and the number of running threads, questions, reloads, and open tables.
799 .RE
800 .TP
801 \fB::mysql::baseinfo\fR \fIoption\fR
802 return information information that do not need handle.
803 .RS
804 .TP
805 \fBconnectparameters\fR
806 return all supported connecting options
807 .TP
808 \fBclientversion\fR
809 return the version of underlying MYSQL C-API library
810 .RE
811 .TP
812 \fB::mysql::ping\fR \fIhandle\fR
813 Checks whether the connection to the server is working. If it has gone down, an automatic reconnection is attempted.
814 .sp
815 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.
816 .sp
817 Return True if server is alive
818 .TP
819 \fB::mysql::changeuser\fR \fIuser\fR \fIpassword\fR ?\fIdatabase\fR?
820 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.
821 .sp
822 ::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
823 .sp
824 if database parameter may be set were is no default database.
825 .sp
826 Cause Error if operation is not succesed
827 .TP
828 \fB::mysql::result\fR \fIhandle\fR \fIoption\fR
829 Return information about the pending result.
830 Note that a result is pending until canceled by a ::mysql::exec command,
831 even if no rows remain to be read.
832 \fIOption\fR must be one of the following keywords.
833 .RS
834 .TP
835 \fBcols\fR
836 Return the number of columns in the pending result.
837 There must be a pending result.
838 .TP
839 \fBcols\fR
840 Return the number of columns in the pending result; an empty string if
841 no result is pending.
842 .TP
843 \fBcurrent\fR
844 Return the current position in the pending result; a non-negative integer.
845 This value can be used as \fIrow-index\fR in the ::mysql::seek command.
846 An error is raised if there is no pending result.
847 .TP
848 \fBcurrent?\fR
849 As above, but returns an empty string if there is no pending result.
850 .TP
851 \fBrows\fR
852 Return the number of rows that can be read sequentially from the
853 current position in the pending result.
854 There must be a pending result.
855 .TP
856 \fBrows\fR
857 Return the number of rows that can be read sequentially from the
858 current position in the pending result; an empty string if no result
859 is pending.
860 .sp
861 [::mysql::result $db current] + [::mysql::result $db rows]
862 always equals the total number of rows in the pending result.
863 .RE
864 .TP
865 \fB::mysql::state\fR \fIhandle\fR ?\fI-numeric\fR?
866 Return the state of a handle as a string or in numeric form.
867 There is no requirement on \fIhandle\fR; it may be any string.
868 The return value is one of the following strings, or the corresponding
869 numeric value if \fI-numeric\fR is specified.
870 The states form a progression where each state builds on the previous.
871 .RS
872 .TP
873 \fBNOT_A_HANDLE (0)\fR
874 The string supplied for \fIhandle\fR is not a mysqltcl handle at all.
875 .TP
876 \fBUNCONNECTED (1)\fR
877 The string supplied for \fIhandle\fR is one of the possible mysqltcl
878 handles, but it is not valid to any server.
879 .TP
880 \fBCONNECTED (2)\fR
881 The handle is connected to a server, but not associated with a database.
882 .TP
883 \fBIN_USE (3)\fR
884 The handle is connected and associated with a database, but there is
885 no pending result.
886 .TP
887 \fBRESULT_PENDING (4)\fR
888 The handle is connected, associated with a database, and there is a
889 pending result.
890 .RE
891 .TP
892 \fB::mysql::close\fR ?\fIhandle\fR?
893 Closes the server connection associated with \fIhandle\fR, causing it
894 to go back to the unconnected state.
895 Closes all connections if \fIhandle\fR is omitted.
896 Returns an empty string.
897 ::mysql::close raises a Tcl error if a handle is specified which is not
898 valid.
899 .TP
900 \fB::mysql::insertid\fR \fIhandle\fR
901 Returns the auto increment id of the last INSERT statement.
902 .TP
903 \fB::mysql::escape\fR ?\fIhandle\fR? \fIstring\fR
904 Returns the content of \fIstring\fR, with all special characters escaped,
905 so that it is suitable for use in an SQL statement. This is simpler (faster)
906 than using a general \fIregexp\fR or string map.
907 If handle is specified C-API function mysql_real_escape_string is used.
908 This is the recommended usage because in this case current character set is respected.
909 .TP
910 \fB::mysql::autocommit\fR \fIhandle\fR \fIboolean\fR
911 Sets autocommit mode on if mode is 1, off if mode is 0.
912 .TP
913 \fB::mysql::commit\fR \fIhandle\fR
914 Commits the current transaction.
915 .TP
916 \fB::mysql::rollback\fR \fIhandle\fR
917 Rollback the current transaction.
918 .TP
919 \fB::mysql::nextresult\fR \fIhandle\fR
920 If more query results exist, mysql::nextresult() reads the next query results and returns the status back to application.
921 returns -1 if no result or number of rows in the result set.
922 .TP
923 \fB::mysql::moreresult\fR \fIhandle\fR
924 Returns true if more results exist from the currently executed query, and the application must call mysql::result to fetch the results.
925 .TP
926 \fB::mysql::warningcount\fR \fIhandle\fR
927 Returns the number of warnings generated during execution of the previous SQL statement.
928 .TP
929 \fB::mysql::isnull\fR \fIvalue\fR
930 Null handling is a known problem with Tcl, especially with DB interaction.
931 The mysql "varchar" type has two valid blank values, NULL and an empty
932 string. This is where the problem arises; Tcl is not able to differentiate
933 between the two because of the way it handles strings.
934 Mysql has new internal Tcl type for null that string representation is stored
935 in global array mysqltcl(nullvalue) and as default empty string.
936 mysql::isnull can be used for safe check for null value.
937 Warning mysql::isnull works only reliable if there are no type conversation on
938 returned rows.
939 Consider row is always Tcl list even when there are only one column in the row.
940 .nf
941 set row [::mysql::next $handle]
942 if {[mysql::isnull [lindex $row 1]]} {
943    puts "2. column of $row is null"
944 }
945 if {[mysql::isnull $row]} {
946    puts "this does not work, because of type conversation list to string"
947 }
948 .fi
949 .TP
950 \fB::mysql::newnull\fR
951 create new null object. It can be used to simulate returned row contents.
952 .TP
953 \fB::mysql::setserveroption\fR \fIhandle\fR \fIoption\fR
954 there are only 2 options now: -multi_statment_on and -multi_statment_off
955 .TP
956 \fB::mysql::shutdown\fR \fIhandle\fR
957 Asks the database server to shut down. The connected user must have SHUTDOWN privileges.
958 .TP
959 \fB::mysql::encoding\fR \fIhandle\fR ?encoding?
960 Ask or change a encoding of connection.
961 There are special encoding "binary" for binary data transfers.
962 .SH "STATUS INFORMATION"
963 Mysqltcl creates and maintains a Tcl global array to provide status
964 information.
965 Its name is \fImysqlstatus\fR.
966 .P
967 Mysqlstatus elements:
968 .TP
969 code
970 A numeric conflict code set after every mysqltcl command.
971 Zero means no conflict; non-zero means some kind of conflict.
972 All conflicts also generate a Tcl error.
973 .sp
974 All MySQL server conflicts set mysqlstatus(code) to the numeric
975 code of the MySQL error.
976 .sp
977 Any other conflict sets mysqlstatus(code) to -1.
978 .TP
979 command
980 The last failing mysqltcl command.
981 Not updated for successful commands.
982 .TP
983 message
984 Message string for the last conflict detected.
985 The same string is returned as the result of the failing mysqltcl
986 command.
987 Not updated for successful commands.
988 .TP
989 nullvalue
990 The string to use in query results to represent the SQL null value.
991 The empty string is used initially.
992 You may set it to another value.
993 .SH "Backward compatibility"
994 Up from version 3.0 all mysql commands are declared in ::mysql namespace.
995 All names for example mysqlconnect are also aviable but deprecated.
996 All old commands have the name pattern mysql{name} and the most of them are now mysql::{name}.
997 The exception is mysqlnext, which  was renamed to mysql::fetch.
998 .SH "BUGS & POSSIBLE MISFEATURES"
999 Deleting any of the mysqltcl commands closes all connections.
1000 .SH "AUTHORS"
1001 .IP \(bu
1002 Tobias Ritzau
1003 .IP \(bu
1004 Paolo Brutti
1005 .IP \(bu
1006 Artur Trzewik (mail@xdobry.de) - active maintainer
1007 MySQLTcl is derived from a patch of msql by Hakan Soderstrom, Soderstrom Programvaruverkstad,
1008 S-12242 Enskede, Sweden.
1009 msql is derived from Sybtcl by Tom Poindexter.
1010 There are many contributors and bug reporter that are not mentioned.
1011 If you have contributed to mysqltcl and wants to be on the list contact Artur Trzewik.