Documentation Source Text

Check-in [7d40b68595]
Login

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

Overview
Comment:Merge changes from 3.10.0.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 7d40b685958ed7407ffb7caa3ed0795865ecb357
User & Date: drh 2016-01-12 13:44:54
Context
2016-01-13
20:52
Add documentation for the fts5 detail= option. check-in: 08f6990b8a user: dan tags: trunk
2016-01-12
13:44
Merge changes from 3.10.0. check-in: 7d40b68595 user: drh tags: trunk
13:44
Fix typos in the TCL interface documentation. check-in: 217ea4895f user: drh tags: branch-3.10
2016-01-11
13:00
Begin entering 3.11.0 changes. check-in: 166fc2da3a user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/tclsqlite.in.

    77     77   
    78     78   <dt><b>-readonly</b> <i>BOOLEAN</i></dt>
    79     79   <dd><p>
    80     80   If true, then open the database file read-only.  If false, then the
    81     81   database is opened for both reading and writing if filesystem permissions
    82     82   allow, or for reading only if filesystem write permission is denied
    83     83   by the operating system.  The default setting is "false".  Note that
    84         -if the previous process to have the database did not exits cleanly
           84  +if the previous process to have the database did not exit cleanly
    85     85   and left behind a [hot journal], then the write permission is required
    86     86   to recover the database after opening, and the database cannot be
    87     87   opened read-only.
    88     88   </p></dd>
    89     89   
    90     90   <dt><b>-uri</b> <i>BOOLEAN</i></dt>
    91     91   <dd><p>
................................................................................
    98     98   <dd><p>
    99     99   Use an alternative [VFS] named by the argument.
   100    100   </p></dd>
   101    101   
   102    102   </dl>
   103    103   </blockquote>
   104    104   
   105         -<p>
   106         -Once an SQLite database is open, it can be controlled using 
   107         -methods of the <i>dbcmd</i>.  There are currently 22 methods
   108         -defined.</p>
   109         -
   110         -<p>
   111         -<ul>
   112         -
   113    105   <tcl>
   114         -foreach m [lsort {
          106  +set method_list [lsort {
   115    107    authorizer
   116    108    backup
   117    109    busy
   118    110    cache
   119    111    changes
   120    112    close
   121    113    collate
................................................................................
   141    133    total_changes
   142    134    trace
   143    135    transaction
   144    136    unlock_notify
   145    137    update_hook
   146    138    version
   147    139    wal_hook
   148         -}] {
   149         - hd_puts "<li><a href=\"#$m\">$m</a></li>"
          140  +}]
          141  +</tcl>
          142  +
          143  +<p>
          144  +Once an SQLite database is open, it can be controlled using 
          145  +methods of the <i>dbcmd</i>.
          146  +<tcl>
          147  +hd_puts "There are currently [llength $method_list] methods\n"
          148  +hd_puts "defined.</p>\n"
          149  +</tcl>
          150  +
          151  +<table border=0 cellpadding=10 width='100%'>
          152  +<tr><td valign='top'><ul>
          153  +<tcl>
          154  +set nbr [expr {int(([llength $method_list]+2)/3)}]
          155  +set i -1
          156  +foreach m $method_list {
          157  +  incr i
          158  +  if {$i==$nbr} {
          159  +    hd_puts "</ul></td>\n<td valign='top'><ul>\n"
          160  +    set i 0
          161  +  }
          162  +  hd_puts "<li><a href=\"#$m\">$m</a></li>\n"
   150    163   }
   151    164   </tcl>
   152         -</ul>
   153         -</p>
          165  +</ul></td></tr>
          166  +</table>
          167  +
   154    168   
   155    169   <p>The use of each of these methods will be explained in the sequel, though
   156    170   not in the order shown above.</p>
   157    171   
   158    172   <tcl>
   159    173   ##############################################################################
   160    174   METHOD eval {
................................................................................
   161    175   <p>
   162    176   The most useful <i>dbcmd</i> method is "eval".  The eval method is used
   163    177   to execute SQL on the database.  The syntax of the eval method looks
   164    178   like this:</p>
   165    179   
   166    180   <blockquote>
   167    181   <i>dbcmd</i>&nbsp;&nbsp;<b>eval</b>&nbsp;&nbsp;<i>sql</i>
   168         -&nbsp;&nbsp;&nbsp;&nbsp;?<i>array-name&nbsp;</i>?&nbsp;?<i>script</i>?
          182  +&nbsp;&nbsp;?<i>array-name</i>?&nbsp;&nbsp;?<i>script</i>?
   169    183   </blockquote>
   170    184   
   171    185   <p>
   172    186   The job of the eval method is to execute the SQL statement or statements
   173    187   given in the second argument.  For example, to create a new table in
   174    188   a database, you can do this:</p>
   175    189   
................................................................................
   279    293   </p>
   280    294   
   281    295   <p>
   282    296   If the $bigstring variable has both a string and a "bytearray" representation,
   283    297   then TCL inserts the value as a string.  If it has only a "bytearray"
   284    298   representation, then the value is inserted as a BLOB.  To force a
   285    299   value to be inserted as a BLOB even if it also has a text representation,
   286         -us a "@" character to in place of the "$".  Like this:
          300  +use a "@" character to in place of the "$".  Like this:
   287    301   </p>
   288    302   
   289    303   <blockquote><b>
   290    304   db1 eval {INSERT INTO t1 VALUES(5,@bigstring)}
   291    305   </b></blockquote>
   292    306   
   293    307   <p>
................................................................................
   364    378   
   365    379   <p>
   366    380   The syntax looks like this:
   367    381   </p>
   368    382   
   369    383   <blockquote>
   370    384   <i>dbcmd</i>&nbsp;&nbsp;<b>transaction</b>&nbsp;&nbsp;<i>?transaction-type?</i>
   371         -&nbsp;&nbsp;<i>SCRIPT,</i>
          385  +&nbsp;&nbsp;<i>script</i>
   372    386   </blockquote>
   373    387   
   374    388   
   375    389   <p>
   376    390   The <i>transaction-type</i> can be one of <b>deferred</b>,
   377    391   <b>exclusive</b> or <b>immediate</b>.  The default is deferred.
   378    392   </p>
................................................................................
   432    446   The "copy" method copies data from a file into a table.
   433    447   It returns the number of rows processed successfully from the file.
   434    448   The syntax of the copy method looks like this:</p>
   435    449   
   436    450   <blockquote>
   437    451   <i>dbcmd</i>&nbsp;&nbsp;<b>copy</b>&nbsp;&nbsp;<i>conflict-algorithm</i>
   438    452   &nbsp;&nbsp;<i>table-name&nbsp;</i>&nbsp;&nbsp;<i>file-name&nbsp;</i>
   439         -&nbsp;&nbsp;&nbsp;&nbsp;?<i>column-separator&nbsp;</i>?
          453  +&nbsp;&nbsp;&nbsp;&nbsp;?<i>column-separator</i>?
   440    454   &nbsp;&nbsp;?<i>null-indicator</i>?
   441    455   </blockquote>
   442    456   
   443    457   <p>Conflict-algorithm must be one of the SQLite conflict algorithms for
   444    458   the INSERT statement: <i>rollback</i>, <i>abort</i>,
   445    459   <i>fail</i>,<i>ignore</i>, or <i>replace</i>. See the SQLite Language
   446    460   section for <a href="lang.html#conflict">ON CONFLICT</a> for more information.
................................................................................
   459    473   The default is an empty string.  Note that column-separator and
   460    474   null-indicator are optional positional arguments; if null-indicator
   461    475   is specified, a column-separator argument must be specified and
   462    476   precede the null-indicator argument.</p>
   463    477   
   464    478   <p>The copy method implements similar functionality to the <b>.import</b>
   465    479   SQLite shell command. 
   466         -The SQLite 2.x <a href="lang.html#copy"><b>COPY</b></a> statement 
   467         -(using the PostgreSQL COPY file format)
   468         -can be implemented with this method as:</p>
   469         -
   470         -<blockquote>
   471         -dbcmd&nbsp;&nbsp;copy&nbsp;&nbsp;$conflictalgo
   472         -&nbsp;&nbsp;$tablename&nbsp;&nbsp;&nbsp;$filename&nbsp;
   473         -&nbsp;&nbsp;&nbsp;&nbsp;\t&nbsp;
   474         -&nbsp;&nbsp;\\N
   475         -</blockquote>
   476         -
   477    480   }
   478    481   
   479    482   ##############################################################################
   480    483   METHOD timeout {
   481    484   
   482    485   <p>The "timeout" method is used to control how long the SQLite library
   483    486   will wait for locks to clear before giving up on a database transaction.
................................................................................
   780    783   ##############################################################################
   781    784   METHOD incrblob {
   782    785   
   783    786   <p>This method opens a TCL channel that can be used to read or write
   784    787   into a preexisting BLOB in the database.  The syntax is like this:</p>
   785    788   
   786    789   <blockquote>
   787         -<i>dbcmd</i>&nbsp;&nbsp;<b>incrblob</b>&nbsp;&nbsp;<b>?-readonly??</b>
          790  +<i>dbcmd</i>&nbsp;&nbsp;<b>incrblob</b>&nbsp;&nbsp;<b>?-readonly?</b>
   788    791   &nbsp;&nbsp;<i>?DB?&nbsp;&nbsp;TABLE&nbsp;&nbsp;COLUMN&nbsp;&nbsp;ROWID</i>
   789    792   </blockquote>
   790    793   
   791    794   <p>
   792    795   The command returns a new TCL channel for reading or writing to the BLOB.
   793    796   The channel is opened using the underlying 
   794    797   <a href="c3ref/blob_open.html">sqlite3_blob_open()</a> C-language
................................................................................
   834    837   written.  <i>Backup-filename</i> does not have to exist ahead of time, but if
   835    838   it does, it must be a well-formed SQLite database.</p>
   836    839   }
   837    840   
   838    841   ##############################################################################
   839    842   METHOD restore {
   840    843   
   841         -<p>The "restore" method copies the content a separate database file 
          844  +<p>The "restore" method copies the content from a separate database file 
   842    845   into the current database connection, overwriting any preexisting content.
   843    846   The command syntax is like this:</p>
   844    847   
   845    848   <blockquote>
   846    849   <i>dbcmd</i>&nbsp;&nbsp;<b>restore</b>&nbsp;&nbsp;?<i>target-database</i>?&nbsp;&nbsp;<i>source-filename</i>
   847    850   </blockquote>
   848    851