Further improvements to documentation in sqlite3session.h.

FossilOrigin-Name: 07019bb9e8d8f2445d1e0342f74ab520e9804cb5

6 files changed, 159 insertions, 36 deletions

diff --git a/ext/session/sqlite3session.h b/ext/session/sqlite3session.h
index 9cf7cda48..dd0e114f7 100644
--- a/ext/session/sqlite3session.h
+++ b/ext/session/sqlite3session.h
@@ -375,7 +375,24 @@ int sqlite3changeset_conflict(
 int sqlite3changeset_finalize(sqlite3_changeset_iter *pIter);
 
 /*
-** Invert a changeset object.
+** This function is used to "invert" a changeset object. Applying an inverted
+** changeset to a database reverses the effects of applying the uninverted
+** changeset. Specifically:
+**
+** <ul>
+**   <li> Each DELETE change is changed to an INSERT, and
+**   <li> Each INSERT change is changed to a DELETE, and
+**   <li> For each UPDATE change, the old.* and new.* values are exchanged.
+** </ul>
+**
+** If successful, a pointer to a buffer containing the inverted changeset
+** is stored in *ppOut, the size of the same buffer is stored in *pnOut, and
+** SQLITE_OK is returned. If an error occurs, both *pnOut and *ppOut are
+** zeroed and an SQLite error code returned.
+**
+** It is the responsibility of the caller to eventually call sqlite3_free()
+** on the *ppOut pointer to free the buffer allocation following a successful 
+** call to this function.
 */
 int sqlite3changeset_invert(
   int nIn, void *pIn,             /* Input changeset */
@@ -383,12 +400,124 @@ int sqlite3changeset_invert(
 );
 
 /*
-** Apply a changeset to a database.
+** Apply a changeset to a database. This function attempts to update the
+** "main" database attached to handle db with the changes found in the
+** changeset passed via the second and third arguments.
+**
+** For each change in the changeset, this function tests that the target
+** database contains a compatible table. A table is considered compatible
+** if all of the following are true:
+**
+** <ul>
+**   <li> The table has the same name as the name recorded in the 
+**        changeset, and
+**   <li> The table has the same number of columns as recorded in the 
+**        changeset, and
+**   <li> The table has primary key columns in the same position as 
+**        recorded in the changeset.
+** </ul>
+**
+** If there is no compatible table, it is not an error, but the change is
+** not applied. A warning message is issued via the sqlite3_log() mechanism
+** with the error code SQLITE_SCHEMA. At most one such warning is issued for
+** each table in the changeset.
+**
+** Otherwise, if there is a compatible table, an attempt is made to modify
+** the table contents according to the UPDATE, INSERT or DELETE change.
+** If a change cannot be applied cleanly, the conflict handler function
+** passed as the fourth argument to sqlite3changeset_apply() may be invoked.
+** A description of exactly when the conflict handler is invoked for each
+** type of change is below.
+**
+** Each time the conflict handler function is invoked, it must return one
+** of [SQLITE_CHANGESET_OMIT], [SQLITE_CHANGESET_ABORT] or 
+** [SQLITE_CHANGESET_REPLACE]. SQLITE_CHANGESET_REPLACE may only be returned
+** if the second argument passed to the conflict handler is either
+** SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If the conflict-handler
+** returns an illegal value, any changes already made are rolled back and
+** the call to sqlite3changeset_apply() returns SQLITE_MISUSE. Different 
+** actions are taken by sqlite3changeset_apply() depending on the value
+** returned by each invocation of the conflict-handler function. Refer to
+** the documentation for the three 
+** [SQLITE_CHANGESET_OMIT|available return values] for details.
+**
+** <dl>
+** <dt>DELETE Changes<dd>
+**   For each DELETE change, this function checks if the target database 
+**   contains a row with the same primary key value (or values) as the 
+**   original row values stored in the changeset. If it does, and the values 
+**   stored in all non-primary key columns also match the values stored in 
+**   the changeset the row is deleted from the target database.
+**
+**   If a row with matching primary key values is found, but one or more of
+**   the non-primary key fields contains a value different from the original
+**   row value stored in the changeset, the conflict-handler function is
+**   invoked with [SQLITE_CHANGESET_DATA] as the second argument.
+**
+**   If no row with matching primary key values is found in the database,
+**   the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
+**   passed as the second argument.
+**
+**   If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT
+**   (which can only happen if a foreign key constraint is violated), the
+**   conflict-handler function is invoked with [SQLITE_CHANGESET_CONSTRAINT]
+**   passed as the second argument. This includes the case where the DELETE
+**   operation is attempted because an earlier call to the conflict handler
+**   function returned [SQLITE_CHANGESET_REPLACE].
+**
+** <dt>INSERT Changes<dd>
+**   For each INSERT change, an attempt is made to insert the new row into
+**   the database.
+**
+**   If the attempt to insert the row fails because the database already 
+**   contains a row with the same primary key values, the conflict handler
+**   function is invoked with the second argument set to 
+**   [SQLITE_CHANGESET_CONFLICT].
+**
+**   If the attempt to insert the row fails because of some other constraint
+**   violation (e.g. NOT NULL or UNIQUE), the conflict handler function is 
+**   invoked with the second argument set to [SQLITE_CHANGESET_CONSTRAINT].
+**   This includes the case where the INSERT operation is re-attempted because 
+**   an earlier call to the conflict handler function returned 
+**   [SQLITE_CHANGESET_REPLACE].
+**
+** <dt>UPDATE Changes<dd>
+**   For each DELETE change, this function checks if the target database 
+**   contains a row with the same primary key value (or values) as the 
+**   original row values stored in the changeset. If it does, and the values 
+**   stored in all non-primary key columns also match the values stored in 
+**   the changeset the row is updated within the target database.
+**
+**   If a row with matching primary key values is found, but one or more of
+**   the non-primary key fields contains a value different from an original
+**   row value stored in the changeset, the conflict-handler function is
+**   invoked with [SQLITE_CHANGESET_DATA] as the second argument. Since
+**   UPDATE changes only contain values for non-primary key fields that are
+**   to be modified, only those fields need to match the original values to
+**   avoid the SQLITE_CHANGESET_DATA conflict-handler callback.
+**
+**   If no row with matching primary key values is found in the database,
+**   the conflict-handler function is invoked with [SQLITE_CHANGESET_NOTFOUND]
+**   passed as the second argument.
+**
+**   If the UPDATE operation is attempted, but SQLite returns 
+**   SQLITE_CONSTRAINT, the conflict-handler function is invoked with 
+**   [SQLITE_CHANGESET_CONSTRAINT] passed as the second argument.
+**   This includes the case where the UPDATE operation is attempted after 
+**   an earlier call to the conflict handler function returned
+**   [SQLITE_CHANGESET_REPLACE].  
+** </dl>
 **
 ** It is safe to execute SQL statements, including those that write to the
 ** table that the callback related to, from within the xConflict callback.
 ** This can be used to further customize the applications conflict
 ** resolution strategy.
+**
+** All changes made by this function are enclosed in a savepoint transaction.
+** If any other error (aside from a constraint failure when attempting to
+** write to the target database) occurs, then the savepoint transaction is
+** rolled back, restoring the target database to its original state, and an 
+** SQLite error code returned.
 */
 int sqlite3changeset_apply(
   sqlite3 *db,                    /* Apply change to "main" db of this handle */
@@ -403,9 +532,10 @@ int sqlite3changeset_apply(
 );
 
 /* 
-** Values passed as the second argument to a conflict-handler.
+** Values that may be passed as the second argument to a conflict-handler.
 **
-** SQLITE_CHANGESET_DATA:
+** <dl>
+** <dt>SQLITE_CHANGESET_DATA<dd>
 **   The conflict handler is invoked with CHANGESET_DATA as the second argument
 **   when processing a DELETE or UPDATE change if a row with the required
 **   PRIMARY KEY fields is present in the database, but one or more other 
@@ -415,7 +545,7 @@ int sqlite3changeset_apply(
 **   The conflicting row, in this case, is the database row with the matching
 **   primary key.
 ** 
-** SQLITE_CHANGESET_NOTFOUND:
+** <dt>SQLITE_CHANGESET_NOTFOUND<dd>
 **   The conflict handler is invoked with CHANGESET_NOTFOUND as the second
 **   argument when processing a DELETE or UPDATE change if a row with the
 **   required PRIMARY KEY fields is not present in the database.
@@ -423,21 +553,22 @@ int sqlite3changeset_apply(
 **   There is no conflicting row in this case. The results of invoking the
 **   sqlite3changeset_conflict() API are undefined.
 ** 
-** SQLITE_CHANGESET_CONFLICT:
+** <dt>SQLITE_CHANGESET_CONFLICT<dd>
 **   CHANGESET_CONFLICT is passed as the second argument to the conflict
-**   handler while processing an UPDATE or an INSERT if the operation would
-**   result in duplicate primary key values.
+**   handler while processing an INSERT change if the operation would result 
+**   in duplicate primary key values.
 ** 
 **   The conflicting row in this case is the database row with the matching
 **   primary key.
 ** 
-** SQLITE_CHANGESET_CONSTRAINT:
+** <dt>SQLITE_CHANGESET_CONSTRAINT<dd>
 **   If any other constraint violation occurs while applying a change (i.e. 
 **   a FOREIGN KEY, UNIQUE, CHECK or NOT NULL constraint), the conflict 
 **   handler is invoked with CHANGESET_CONSTRAINT as the second argument.
 ** 
 **   There is no conflicting row in this case. The results of invoking the
 **   sqlite3changeset_conflict() API are undefined.
+** </dl>
 */
 #define SQLITE_CHANGESET_DATA       1
 #define SQLITE_CHANGESET_NOTFOUND   2
@@ -447,12 +578,13 @@ int sqlite3changeset_apply(
 /* 
 ** Valid return values from a conflict-handler.
 **
-** SQLITE_CHANGESET_OMIT:
+** <dl>
+** <dt>SQLITE_CHANGESET_OMIT<dd>
 **   If a conflict handler returns this value no special action is taken. The
-**   change is not applied. The session module continues to the next change
-**   in the changeset.
+**   change that caused the conflict is not applied. The session module 
+**   continues to the next change in the changeset.
 **
-** SQLITE_CHANGESET_REPLACE:
+** <dt>SQLITE_CHANGESET_REPLACE<dd>
 **   This value may only be returned if the second argument to the conflict
 **   handler was SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. If this
 **   is not the case, any changes applied so far are rolled back and the 
@@ -467,9 +599,10 @@ int sqlite3changeset_apply(
 **   second attempt to apply the change is made. If this second attempt fails,
 **   the original row is restored to the database before continuing.
 **
-** SQLITE_CHANGESET_ABORT:
+** <dt>SQLITE_CHANGESET_ABORT<dd>
 **   If this value is returned, any changes applied so far are rolled back 
-**   and the call to sqlite3changeset_apply() returns SQLITE_MISUSE.
+**   and the call to sqlite3changeset_apply() returns SQLITE_ABORT.
+** </dl>
 */
 #define SQLITE_CHANGESET_OMIT       0
 #define SQLITE_CHANGESET_REPLACE    1
diff --git a/install-sh b/install-sh
index e9de23842..e9de23842 100755..100644
--- a/install-sh
+++ b/install-sh
diff --git a/manifest b/manifest
index 47e703722..f680f79bc 100644
--- a/manifest
+++ b/manifest
@@ -1,8 +1,5 @@
------BEGIN PGP SIGNED MESSAGE-----
-Hash: SHA1
-
-C Fix\sa\smemory\sallocation\sissues\sin\sthe\spreupdate\shook\sso\sthat\sthe\shook.test\nscript\sruns\sclean\sin\svalgrind.
-D 2011-03-18T15:13:31.545
+C Further\simprovements\sto\sdocumentation\sin\ssqlite3session.h.
+D 2011-03-18T16:13:53
 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
 F Makefile.in 27701a1653595a1f2187dc61c8117e00a6c1d50f
 F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
@@ -103,9 +100,9 @@ F ext/rtree/sqlite3rtree.h 1af0899c63a688e272d69d8e746f24e76f10a3f0
 F ext/rtree/tkt3363.test 142ab96eded44a3615ec79fba98c7bde7d0f96de
 F ext/rtree/viewrtree.tcl eea6224b3553599ae665b239bd827e182b466024
 F ext/session/sqlite3session.c 4183792547af5b5d3ec1c8a3f858beb172682503
-F ext/session/sqlite3session.h 3e342facbb95589dfba34545df383df68cc44ebf
+F ext/session/sqlite3session.h 9551c002efd5fde07c52994c6b592308e0df2d6a
 F ext/session/test_session.c 2559ef68e421c7fb83e2c19ef08a17343b70d535
-F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895 x
+F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895
 F ltmain.sh 3ff0879076df340d2e23ae905484d8c15d5fdea8
 F main.mk ae0868e05c76eaa8a0ae3d6927a949b1c8e810d7
 F mkdll.sh 7d09b23c05d56532e9d44a50868eb4b12ff4f74a
@@ -608,7 +605,7 @@ F test/permutations.test 5b2a4cb756ffb2407cb4743163668d1d769febb6
 F test/pragma.test fdfc09067ea104a0c247a1a79d8093b56656f850
 F test/pragma2.test 5364893491b9231dd170e3459bfc2e2342658b47
 F test/printf.test 05970cde31b1a9f54bd75af60597be75a5c54fea
-F test/progress.test 5b075c3c790c7b2a61419bc199db87aaf48b8301
+F test/progress.test 5b075c3c790c7b2a61419bc199db87aaf48b8301 x
 F test/ptrchng.test ef1aa72d6cf35a2bbd0869a649b744e9d84977fc
 F test/quick.test 1681febc928d686362d50057c642f77a02c62e57
 F test/quota.test ddafe133653093eb9a99ccd6264884ae43f9c9b8
@@ -896,7 +893,7 @@ F tool/genfkey.test 4196a8928b78f51d54ef58e99e99401ab2f0a7e5
 F tool/lemon.c dfd81a51b6e27e469ba21d01a75ddf092d429027
 F tool/lempar.c 01ca97f87610d1dac6d8cd96ab109ab1130e76dc
 F tool/mkkeywordhash.c d2e6b4a5965e23afb80fbe74bb54648cd371f309
-F tool/mkopts.tcl 66ac10d240cc6e86abd37dc908d50382f84ff46e
+F tool/mkopts.tcl 66ac10d240cc6e86abd37dc908d50382f84ff46e x
 F tool/mkspeedsql.tcl a1a334d288f7adfe6e996f2e712becf076745c97
 F tool/mksqlite3c.tcl cf44512a48112b1ba09590548660a5a6877afdb3
 F tool/mksqlite3h.tcl d76c226a5e8e1f3b5f6593bcabe5e98b3b1ec9ff
@@ -921,14 +918,7 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
 F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f
-P e73e9082f3b14088752717193a10dd7657deb8af
-R 150a0d4d8ebf26c7dc0eae89afa852c9
-U drh
-Z f580a5a873ab613c2a5bfc6ce81e4e03
------BEGIN PGP SIGNATURE-----
-Version: GnuPG v1.4.6 (GNU/Linux)
-
-iD8DBQFNg3aeoxKgR168RlERAnluAJ9mJTScCzmLzWj8hzyPNreCvcU53ACcDZ+U
-AOCmfmp9NGd52IWhvYcR1co=
-=4fKC
------END PGP SIGNATURE-----
+P bd94f4c8b1c4590c437030f0122015f1a37e2582
+R fb83d41281a4d5ba8505f15c6f6b6372
+U dan
+Z ff00d37e3af9047c8539a141cf64a629
diff --git a/manifest.uuid b/manifest.uuid
index 8974aa69d..c2dbebadb 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-bd94f4c8b1c4590c437030f0122015f1a37e2582
\ No newline at end of file
+07019bb9e8d8f2445d1e0342f74ab520e9804cb5
\ No newline at end of file
diff --git a/test/progress.test b/test/progress.test
index b25a10053..b25a10053 100644..100755
--- a/test/progress.test
+++ b/test/progress.test
diff --git a/tool/mkopts.tcl b/tool/mkopts.tcl
index e3ddcb9ee..e3ddcb9ee 100644..100755
--- a/tool/mkopts.tcl
+++ b/tool/mkopts.tcl