Documentation Source Text

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

Changes to pages/changes.in.

    24     24   chng {2018-02-00 (3.22.0)} {
    25     25   <li> The output of [sqlite3_trace_v2()] now shows each individual SQL statements
    26     26        run within a trigger.
    27     27   <li> Add the ability to read from [WAL mode] databases even if the application 
    28     28        lacks write permission on the database and its containing directory, as long as
    29     29        the -shm and -wal files exist in that directory.
    30     30   <li> Added the [rtreecheck()] scalar SQL function to the [R-Tree extension].
    31         -<li> Added the [sqlite3_vtab_nochange()] interface to help virtual table implementations
    32         -     optimize UPDATE operations.
           31  +<li> Added the [sqlite3_vtab_nochange()] and [sqlite3_value_nochange()] interfaces
           32  +     to help virtual table implementations optimize UPDATE operations.
    33     33   <li> Added support for the [FTS5 initial token|"&#94;" initial token syntax] in FTS5.
    34     34   <li> New extensions:
    35     35   <ol type='a'>
    36     36     <li> The [Zipfile virtual table] can read and write a 
    37     37          [https://en.wikipedia.org/wiki/Zip_(file_format)|ZIP Archive].
    38     38     <li> Added the fsdir(PATH) [table-valued function] to the
    39     39          [https://sqlite.org/src/file/ext/misc/fileio.c|fileio.c] extension,

Changes to pages/vtab.in.

  1172   1172   using functions such as [sqlite3_mprintf()] or [sqlite3_malloc()].
  1173   1173   
  1174   1174   <p>If the xUpdate method violates some constraint of the virtual table
  1175   1175   (including, but not limited to, attempting to store a value of the wrong 
  1176   1176   datatype, attempting to store a value that is too
  1177   1177   large or too small, or attempting to change a read-only value) then the
  1178   1178   xUpdate must fail with an appropriate [error code].
         1179  +
         1180  +<p>If the xUpdate method is performaing an UPDATE, then
         1181  +[sqlite3_value_nochange(X)] can be used to discover which columns
         1182  +of the virtual table were actually modified by the UPDATE
         1183  +statement.  The [sqlite3_value_nochange(X)] interface returns
         1184  +true for columns that do not change.
         1185  +On every UPDATE, SQLite will first invoke
         1186  +[xColumn] separately for each unchanging column in the table to 
         1187  +obtain the value for that column.  The [xColumn] method can
         1188  +check to see if the column is unchanged by invoking
         1189  +[sqlite3_vtab_nochange()].  If [xColumn] sees that the column
         1190  +is not being modified, it can return without setting a result
         1191  +using one of the [sqlite3_result_int|sqlite3_result_xxxxx()]
         1192  +interfaces.  In that case [sqlite3_value_nochange()] will be
         1193  +true within the xUpdate method.  However, if [xColumn]
         1194  +invokes one or more [sqlite3_result_int|sqlite3_result_xxxxx()]
         1195  +interfaces, then the [sqlite3_value_nochange()] for that
         1196  +column will be false within xUpdate.
  1179   1197   
  1180   1198   <p>There might be one or more [sqlite3_vtab_cursor] objects open and in use 
  1181   1199   on the virtual table instance and perhaps even on the row of the virtual
  1182   1200   table when the xUpdate method is invoked.  The implementation of
  1183   1201   xUpdate must be prepared for attempts to delete or modify rows of the table
  1184   1202   out from other existing cursors.  If the virtual table cannot accommodate
  1185   1203   such changes, the xUpdate method must return an [error code].