/ Check-in [94aa2d32]
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

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

Overview
Comment:Updates to the documentation on the TCL bindings. (CVS 2692)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 94aa2d32459e1cee2df21fcc7df76c73dab903cd
User & Date: drh 2005-09-13 07:00:06
Context
2005-09-13
16:12
Correct the sense of a test for SQLITE_DEBUG on the resent NDEBUG change. Ticket #1425 (CVS 2693) check-in: 81fdffdf user: drh tags: trunk
07:00
Updates to the documentation on the TCL bindings. (CVS 2692) check-in: 94aa2d32 user: drh tags: trunk
00:02
Fix a comment typo in the previous check-in. (CVS 2691) check-in: 49c95280 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to www/tclsqlite.tcl.

     1      1   #
     2      2   # Run this Tcl script to generate the tclsqlite.html file.
     3      3   #
     4         -set rcsid {$Id: tclsqlite.tcl,v 1.14 2005/08/02 17:38:19 drh Exp $}
            4  +set rcsid {$Id: tclsqlite.tcl,v 1.15 2005/09/13 07:00:06 drh Exp $}
     5      5   source common.tcl
     6      6   header {The Tcl interface to the SQLite library}
     7      7   proc METHOD {name text} {
     8      8     puts "<a name=\"$name\">\n<h3>The \"$name\" method</h3>\n"
     9      9     puts $text
    10     10   }
    11     11   puts {
................................................................................
    37     37   command to control the database.  The name of the new Tcl command
    38     38   is given by the first argument.  This approach is similar to the
    39     39   way widgets are created in Tk.
    40     40   </p>
    41     41   
    42     42   <p>
    43     43   The name of the database is just the name of a disk file in which
    44         -the database is stored.
           44  +the database is stored.  If the name of the database is an empty
           45  +string or the special name ":memory:" then a new database is created
           46  +in memory.
    45     47   </p>
    46     48   
    47     49   <p>
    48     50   Once an SQLite database is open, it can be controlled using 
    49         -methods of the <i>dbcmd</i>.  There are currently 19 methods
           51  +methods of the <i>dbcmd</i>.  There are currently 21 methods
    50     52   defined:</p>
           53  +
           54  +<p>The <b>sqlite3</b> also accepts an optional third argument called
           55  +the "mode".  This argument is a legacy from SQLite version 2 and is
           56  +currently ignored.</p>
    51     57   
    52     58   <p>
    53     59   <ul>
    54     60   }
    55     61   foreach m [lsort {
    56     62    authorizer
    57     63    busy
           64  + cache
    58     65    changes
    59     66    close
    60     67    collate
    61     68    collation_needed
    62     69    commit_hook
    63     70    complete
    64     71    copy
................................................................................
    81     88   </p>
    82     89   
    83     90   <p>The use of each of these methods will be explained in the sequel, though
    84     91   not in the order shown above.</p>
    85     92   
    86     93   }
    87     94   
    88         -##############################################################################
    89         -METHOD close {
    90         -
    91         -<p>
    92         -As its name suggests, the "close" method to an SQLite database just
    93         -closes the database.  This has the side-effect of deleting the
    94         -<i>dbcmd</i> Tcl command.  Here is an example of opening and then
    95         -immediately closing a database:
    96         -</p>
    97         -
    98         -<blockquote>
    99         -<b>sqlite3 db1 ./testdb<br>
   100         -db1 close</b>
   101         -</blockquote>
   102         -
   103         -<p>
   104         -If you delete the <i>dbcmd</i> directly, that has the same effect
   105         -as invoking the "close" method.  So the following code is equivalent
   106         -to the previous:</p>
   107         -
   108         -<blockquote>
   109         -<b>sqlite3 db1 ./testdb<br>
   110         -rename db1 {}</b>
   111         -</blockquote>
   112         -}
   113         -
   114     95   ##############################################################################
   115     96   METHOD eval {
   116     97   <p>
   117     98   The most useful <i>dbcmd</i> method is "eval".  The eval method is used
   118     99   to execute SQL on the database.  The syntax of the eval method looks
   119    100   like this:</p>
   120    101   
................................................................................
   226    207   Note that it is not necessary to quote the $bigblob value.  That happens
   227    208   automatically.  If $bigblob is a large string or binary object, this
   228    209   technique is not only easier to write, it is also much more efficient
   229    210   since it avoids making a copy of the content of $bigblob.
   230    211   </p>
   231    212   
   232    213   }
          214  +
          215  +##############################################################################
          216  +METHOD close {
          217  +
          218  +<p>
          219  +As its name suggests, the "close" method to an SQLite database just
          220  +closes the database.  This has the side-effect of deleting the
          221  +<i>dbcmd</i> Tcl command.  Here is an example of opening and then
          222  +immediately closing a database:
          223  +</p>
          224  +
          225  +<blockquote>
          226  +<b>sqlite3 db1 ./testdb<br>
          227  +db1 close</b>
          228  +</blockquote>
          229  +
          230  +<p>
          231  +If you delete the <i>dbcmd</i> directly, that has the same effect
          232  +as invoking the "close" method.  So the following code is equivalent
          233  +to the previous:</p>
          234  +
          235  +<blockquote>
          236  +<b>sqlite3 db1 ./testdb<br>
          237  +rename db1 {}</b>
          238  +</blockquote>
          239  +}
   233    240   
   234    241   ##############################################################################
   235    242   METHOD transaction {
   236    243   
   237    244   <p>
   238    245   The "transaction" method is used to execute a TCL script inside an SQLite
   239    246   database transaction.  The transaction is committed when the script completes,
................................................................................
   264    271   
   265    272   
   266    273   <p>
   267    274   The <i>transaction-type</i> can be one of <b>deferred</b>,
   268    275   <b>exclusive</b> or <b>immediate</b>.  The default is deferred.
   269    276   </p>
   270    277   }
          278  +
          279  +##############################################################################
          280  +METHOD cache {
          281  +
          282  +<p>
          283  +The "eval" method described <a href="#eval">above</a> keeps a cache of
          284  +<a href="capi3ref.html#sqlite3_prepare">prepared statements</a>
          285  +for recently evaluated SQL commands.  
          286  +The "cache" method is used to control this cache.
          287  +The first form of this command is:</p>
          288  +
          289  +<blockquote>
          290  +<i>dbcmd</i>&nbsp;&nbsp;<b>cache size</b>&nbsp;&nbsp;<i>N</i>
          291  +</blockquote>
          292  +
          293  +<p>This sets the maximum number of statements that can be cached.
          294  +The upper limit is 100.  The default is 10.  If you set the cache size
          295  +to 0, no caching is done.</p>
          296  +
          297  +<p>The second form of the command is this:</p>
          298  +
          299  +
          300  +<blockquote>
          301  +<i>dbcmd</i>&nbsp;&nbsp;<b>cache flush</b>
          302  +</blockquote>
          303  +
          304  +<p>The cache-flush method 
          305  +<a href="capi3ref.html#sqlite3_finalize">finalizes</a>
          306  +all prepared statements currently
          307  +in the cache.</p>
          308  +
          309  +}
   271    310   
   272    311   ##############################################################################
   273    312   METHOD complete {
   274    313   
   275    314   <p>
   276    315   The "complete" method takes a string of supposed SQL as its only argument.
   277    316   It returns TRUE if the string is a complete statement of SQL and FALSE if
   278    317   there is more to be entered.</p>
   279    318   
   280    319   <p>The "complete" method is useful when building interactive applications
   281    320   in order to know when the user has finished entering a line of SQL code.
   282         -This is really just an interface to the <b>sqlite3_complete()</b> C
   283         -function.  Refer to the <a href="c_interface.html">C/C++ interface</a>
   284         -specification for additional information.</p>
          321  +This is really just an interface to the 
          322  +<a href="capi3ref.html#sqlite3_complete"><b>sqlite3_complete()</b></a> C
          323  +function.
   285    324   }
   286    325   
   287    326   ##############################################################################
   288    327   METHOD copy {
   289    328   
   290    329   <p>
   291    330   The "copy" method copies data from a file into a table.
................................................................................
   422    461   }
   423    462   
   424    463   
   425    464   
   426    465   ##############################################################################
   427    466   METHOD onecolumn {
   428    467   
   429         -<p>The "onecolumn" method works like "eval" in that it evaluates the
          468  +<p>The "onecolumn" method works like 
          469  +"<a href="#eval">eval</a>" in that it evaluates the
   430    470   SQL query statement given as its argument.  The difference is that
   431    471   "onecolumn" returns a single element which is the first column of the
   432    472   first row of the query result.</p>
   433    473   
   434    474   <p>This is a convenience method.  It saves the user from having to
   435    475   do a "<tt>[lindex&nbsp;...&nbsp;0]</tt>" on the results of an "eval"
   436    476   in order to extract a single column result.</p>
................................................................................
   451    491   in the database that were inserted, deleted, and/or modified since the
   452    492   current database connection was first opened.</p>
   453    493   }
   454    494   
   455    495   ##############################################################################
   456    496   METHOD authorizer {
   457    497   
   458         -<p>The "authorizer" method provides access to the sqlite3_set_authorizer
          498  +<p>The "authorizer" method provides access to the 
          499  +<a href="capi3ref.html#sqlite3_set_authorizer">sqlite3_set_authorizer</a>
   459    500   C/C++ interface.  The argument to authorizer is the name of a procedure that
   460    501   is called when SQL statements are being compiled in order to authorize
   461    502   certain operations.  The callback procedure takes 5 arguments which describe
   462    503   the operation being coded.  If the callback returns the text string
   463    504   "SQLITE_OK", then the operation is allowed.  If it returns "SQLITE_IGNORE",
   464    505   then the operation is silently disabled.  If the return is "SQLITE_DENY"
   465    506   then the compilation fails with an error.