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