Documentation Source Text

Check-in [13bb521f7e]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add documentation on the enable_load_extension method in the TCL interface.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 13bb521f7e4b297b03dc24c93d281b7b705304e6
User & Date: drh 2008-07-16 18:58:22.000
Context
2008-07-21
22:44
Added system requirements document. (check-in: 715f11e50d user: drh tags: trunk)
2008-07-16
18:58
Add documentation on the enable_load_extension method in the TCL interface. (check-in: 13bb521f7e user: drh tags: trunk)
18:49
Reverted accidentally checked-in local MAkefile change. (check-in: 6308f3b20a user: mihailim tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/lang.in.
1254
1255
1256
1257
1258
1259
1260

1261
1262
1263
1264
1265
1266
1267
  hd_puts "<td valign=\"top\" align=\"right\" width=\"120\">$syntax</td>"
  hd_puts {<td valign="top">}
  if {[llength $keywords]==0} {
    regexp {[a-z_]+} $syntax name
    hd_fragment $name $name
  } else {
    eval hd_fragment $keywords

  }
  hd_resolve $desc
  hd_puts {</td></tr>}
}
</tcl>

<p>The core functions shown below are available by default. 







>







1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
  hd_puts "<td valign=\"top\" align=\"right\" width=\"120\">$syntax</td>"
  hd_puts {<td valign="top">}
  if {[llength $keywords]==0} {
    regexp {[a-z_]+} $syntax name
    hd_fragment $name $name
  } else {
    eval hd_fragment $keywords
    hd_keywords $keywords
  }
  hd_resolve $desc
  hd_puts {</td></tr>}
}
</tcl>

<p>The core functions shown below are available by default. 
Changes to pages/tclsqlite.in.
1
2
3
4
5
6
7
8
9
10
11
12
<title>The Tcl interface to the SQLite library</title>
<tcl>
proc METHOD {name text} {
  hd_puts "<a name=\"$name\"></a>\n<h3>The \"$name\" method</h3>\n"
  hd_puts $text
}
</tcl>

<h2>The Tcl interface to the SQLite library</h2>

<p>The SQLite library is designed to be very easy to use from
a Tcl or Tcl/Tk script.  This document gives an overview of the Tcl




|







1
2
3
4
5
6
7
8
9
10
11
12
<title>The Tcl interface to the SQLite library</title>
<tcl>
proc METHOD {name text} {
  hd_puts "<a name=\"$name\"></a>\n<h3>The \"$name\" method</h3>\n"
  hd_resolve $text
}
</tcl>

<h2>The Tcl interface to the SQLite library</h2>

<p>The SQLite library is designed to be very easy to use from
a Tcl or Tcl/Tk script.  This document gives an overview of the Tcl
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
query requests 2 columns and there are 3 rows matching the query,
then the returned list will contain 6 elements.  For example:</p>

<blockquote>
<b>db1 eval {INSERT INTO t1 VALUES(1,'hello')}<br>
db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}<br>
db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}<br>
set x [db1 eval {SELECT * FROM t1 ORDER BY a}]</b>
</blockquote>

<p>The variable <b>$x</b> is set by the above code to</p>

<blockquote>
<b>1 hello 2 goodbye 3 howdy!</b>
</blockquote>







|







120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
query requests 2 columns and there are 3 rows matching the query,
then the returned list will contain 6 elements.  For example:</p>

<blockquote>
<b>db1 eval {INSERT INTO t1 VALUES(1,'hello')}<br>
db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}<br>
db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}<br>
set x &#91;db1 eval {SELECT * FROM t1 ORDER BY a}&#93;</b>
</blockquote>

<p>The variable <b>$x</b> is set by the above code to</p>

<blockquote>
<b>1 hello 2 goodbye 3 howdy!</b>
</blockquote>
429
430
431
432
433
434
435
















436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
database.  This callback can do whatever is desired.  Presumably, the
callback will do some other useful work for a short while (such as service
GUI events) then return
so that the lock can be tried again.  The callback procedure should
return "0" if it wants SQLite to try again to open the database and
should return "1" if it wants SQLite to abandon the current operation.
}

















##############################################################################
METHOD exists {

<p>The "exists" method is similar to "onecolumn" and "eval" in that
it executes SQL statements.  The difference is that the "exists" method
always returns a boolean value which is TRUE if a query in the SQL
statement it executes returns one or more rows and FALSE if the SQL
returns an empty set.</p>

<p>The "exists" method is often used to test for the existance of
rows in a table.  For example:</p>

<blockquote><b>
if {[db exists {SELECT 1 FROM table1 WHERE user=$user}]} {<br>
&nbsp;&nbsp;&nbsp;# Processing if $user exists<br>
} else {<br>
&nbsp;&nbsp;&nbsp;# Processing if $user does not exist<br>
}
</b></blockquote>
}








>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>














|







429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
database.  This callback can do whatever is desired.  Presumably, the
callback will do some other useful work for a short while (such as service
GUI events) then return
so that the lock can be tried again.  The callback procedure should
return "0" if it wants SQLite to try again to open the database and
should return "1" if it wants SQLite to abandon the current operation.
}

##############################################################################
METHOD enable_load_extension {

<p>The extension loading mechanism of SQLite (accessed using the
[load_extension()] SQL function) is turned off by default.  This is
a security precaution.  If an application wants to make use of the
[load_extension()] function it must first turn the capability on using
this method.</p>

<p>This method takes a single boolean argument which will turn the
extension loading functionality on or off.</p>

<p>This method maps to the [sqlite3_enable_load_extension()] C/C++
interface.</p>
}

##############################################################################
METHOD exists {

<p>The "exists" method is similar to "onecolumn" and "eval" in that
it executes SQL statements.  The difference is that the "exists" method
always returns a boolean value which is TRUE if a query in the SQL
statement it executes returns one or more rows and FALSE if the SQL
returns an empty set.</p>

<p>The "exists" method is often used to test for the existance of
rows in a table.  For example:</p>

<blockquote><b>
if {&#91;db exists {SELECT 1 FROM table1 WHERE user=$user}&#93;} {<br>
&nbsp;&nbsp;&nbsp;# Processing if $user exists<br>
} else {<br>
&nbsp;&nbsp;&nbsp;# Processing if $user does not exist<br>
}
</b></blockquote>
}

506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
<p>The "onecolumn" method works like 
"<a href="#eval">eval</a>" in that it evaluates the
SQL query statement given as its argument.  The difference is that
"onecolumn" returns a single element which is the first column of the
first row of the query result.</p>

<p>This is a convenience method.  It saves the user from having to
do a "<tt>[lindex&nbsp;...&nbsp;0]</tt>" on the results of an "eval"
in order to extract a single column result.</p>
}

##############################################################################
METHOD changes {

<p>The "changes" method returns an integer which is the number of rows







|







522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
<p>The "onecolumn" method works like 
"<a href="#eval">eval</a>" in that it evaluates the
SQL query statement given as its argument.  The difference is that
"onecolumn" returns a single element which is the first column of the
first row of the query result.</p>

<p>This is a convenience method.  It saves the user from having to
do a "<tt>&#91;lindex&nbsp;...&nbsp;0&#93;</tt>" on the results of an "eval"
in order to extract a single column result.</p>
}

##############################################################################
METHOD changes {

<p>The "changes" method returns an integer which is the number of rows
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586

<p>For example, the following code implements a collating sequence called
"NOCASE" that sorts in text order without regard to case:
</p>

<blockquote><b>
proc nocase_compare {a b} {<br>
&nbsp;&nbsp;&nbsp;&nbsp;return [string compare [string tolower $a] [string tolower $b]]<br>
}<br>
db collate NOCASE nocase_compare<br>
</b></blockquote>
}

##############################################################################
METHOD collation_needed {







|







588
589
590
591
592
593
594
595
596
597
598
599
600
601
602

<p>For example, the following code implements a collating sequence called
"NOCASE" that sorts in text order without regard to case:
</p>

<blockquote><b>
proc nocase_compare {a b} {<br>
&nbsp;&nbsp;&nbsp;&nbsp;return &#91;string compare &#91;string tolower $a&#93; &#91;string tolower $b&#93;&#93;<br>
}<br>
db collate NOCASE nocase_compare<br>
</b></blockquote>
}

##############################################################################
METHOD collation_needed {