Add missing source code comments and fix other issues with the new code on this branch.

FossilOrigin-Name: df39fbe9ab87937beb77af353cd55602290b185e222e0a92a3ebf9a9a0b9e2e7

ext/session/sqlite3session.c

@@ -122,7 +122,15 @@ struct sqlite3_changeset_iter {
 **
 ** pDfltStmt:
 **   This is only used by the sqlite3changegroup_xxx() APIs, not by
-**   regular sqlite3_session objects.
+**   regular sqlite3_session objects. It is a SELECT statement that
+**   selects the default value for each table column. For example,
+**   if the table is 
+**
+**      CREATE TABLE xx(a DEFAULT 1, b, c DEFAULT 'abc')
+**
+**   then this variable is the compiled version of:
+**
+**      SELECT 1, NULL, 'abc'
 */
 struct SessionTable {
   SessionTable *pNext;
@@ -136,7 +144,6 @@ struct SessionTable {
   int nEntry;                     /* Total number of entries in hash table */
   int nChange;                    /* Size of apChange[] array */
   SessionChange **apChange;       /* Hash table buckets */
-
   sqlite3_stmt *pDfltStmt;
 };
 
@@ -1002,13 +1009,14 @@ static int sessionGrowHash(
 **
 ** For example, if the table is declared as:
 **
-**     CREATE TABLE tbl1(w, x, y, z, PRIMARY KEY(w, z));
+**     CREATE TABLE tbl1(w, x DEFAULT 'abc', y, z, PRIMARY KEY(w, z));
 **
-** Then the four output variables are populated as follows:
+** Then the five output variables are populated as follows:
 **
 **     *pnCol  = 4
 **     *pzTab  = "tbl1"
 **     *pazCol = {"w", "x", "y", "z"}
+**     *pazDflt = {NULL, 'abc', NULL, NULL}
 **     *pabPK  = {1, 0, 0, 1}
 **
 ** All returned buffers are part of the same single allocation, which must
@@ -1156,10 +1164,9 @@ static int sessionTableInfo(
 }
 
 /*
-** This function is only called from within a pre-update handler for a
-** write to table pTab, part of session pSession. If this is the first
-** write to this table, initalize the SessionTable.nCol, azCol[] and
-** abPK[] arrays accordingly.
+** This function is called to initialize the SessionTable.nCol, azCol[]
+** abPK[] and azDflt[] members of SessionTable object pTab. If these
+** fields are already initilialized, this function is a no-op.
 **
 ** If an error occurs, an error code is stored in sqlite3_session.rc and
 ** non-zero returned. Or, if no error occurs but the table has no primary
@@ -1168,10 +1175,10 @@ static int sessionTableInfo(
 ** is set to NULL in this case.
 */
 static int sessionInitTable(
-  sqlite3_session *pSession,
-  SessionTable *pTab,
-  sqlite3 *db,
-  const char *zDb
+  sqlite3_session *pSession,      /* Optional session handle */
+  SessionTable *pTab,             /* Table object to initialize */
+  sqlite3 *db,                    /* Database handle to read schema from */
+  const char *zDb                 /* Name of db - "main", "temp" etc. */
 ){
   int rc = SQLITE_OK;
 
@@ -1209,6 +1216,9 @@ static int sessionInitTable(
   return rc;
 }
 
+/*
+** Re-initialize table object pTab.
+*/
 static int sessionReinitTable(sqlite3_session *pSession, SessionTable *pTab){
   int nCol = 0;
   const char **azCol = 0;
@@ -1258,12 +1268,17 @@ static int sessionReinitTable(sqlite3_session *pSession, SessionTable *pTab){
   return pSession->rc;
 }
 
+/*
+** Session-change object (*pp) contains an old.* record with fewer than
+** nCol fields. This function updates it with the default values for
+** the missing fields.
+*/
 static void sessionUpdateOneChange(
-  sqlite3_session *pSession,
-  int *pRc,
-  SessionChange **pp, 
-  int nCol, 
-  sqlite3_stmt *pDflt
+  sqlite3_session *pSession,      /* For memory accounting */
+  int *pRc,                       /* IN/OUT: Error code */
+  SessionChange **pp,             /* IN/OUT: Change object to update */
+  int nCol,                       /* Number of columns now in table */
+  sqlite3_stmt *pDflt             /* SELECT <default-values...> */
 ){
   SessionChange *pOld = *pp;
 
@@ -1414,6 +1429,10 @@ static void sessionAppendStr(
   }
 }
 
+/*
+** Format a string using printf() style formatting and then append it to the
+** buffer using sessionAppendString().
+*/
 static void sessionAppendPrintf(
   SessionBuffer *p,               /* Buffer to append to */
   int *pRc, 
@@ -1471,6 +1490,11 @@ static int sessionPrepareDfltStmt(
   return rc;
 }
 
+/*
+** Table pTab has one or more existing change-records with old.* records
+** with fewer than pTab->nCol columns. This function updates all such 
+** change-records with the default values for the missing columns.
+*/
 static int sessionUpdateChanges(sqlite3_session *pSession, SessionTable *pTab){
   sqlite3_stmt *pStmt = 0;
   int rc = pSession->rc;
@@ -2969,13 +2993,6 @@ static int sessionGenerateChangeset(
   for(pTab=pSession->pTable; rc==SQLITE_OK && pTab; pTab=pTab->pNext){
     if( pTab->nEntry ){
       const char *zName = pTab->zName;
-
-#if 0
-      int nCol = 0;               /* Number of columns in table */
-      u8 *abPK = 0;               /* Primary key array */
-      int bRowid = 0;
-      const char **azCol = 0;     /* Table columns */
-#endif
       int i;                      /* Used to iterate through hash buckets */
       sqlite3_stmt *pSel = 0;     /* SELECT statement to query table pTab */
       int nRewind = buf.nBuf;     /* Initial size of write buffer */
@@ -5904,6 +5921,9 @@ int sqlite3changegroup_new(sqlite3_changegroup **pp){
   return rc;
 }
 
+/*
+** Provide a database schema to the changegroup object.
+*/
 int sqlite3changegroup_schema(
   sqlite3_changegroup *pGrp, 
   sqlite3 *db, 

manifest

@@ -1,5 +1,5 @@
-C Update\sthis\sbranch\swith\slatest\schanges\sfrom\sthe\strunk.
-D 2023-10-06T19:46:19.137
+C Add\smissing\ssource\scode\scomments\sand\sfix\sother\sissues\swith\sthe\snew\scode\son\sthis\sbranch.
+D 2023-10-06T20:39:42.133
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -545,7 +545,7 @@ F ext/session/sessionrowid.test 85187c2f1b38861a5844868126f69f9ec62223a03449a98a
 F ext/session/sessionsize.test 8fcf4685993c3dbaa46a24183940ab9f5aa9ed0d23e5fb63bfffbdb56134b795
 F ext/session/sessionstat1.test b039e38e2ba83767b464baf39b297cc0b1cc6f3292255cb467ea7e12d0d0280c
 F ext/session/sessionwor.test 6fd9a2256442cebde5b2284936ae9e0d54bde692d0f5fd009ecef8511f4cf3fc
-F ext/session/sqlite3session.c fdf5d63f7e2f722938ce4aee18d472a8fae90f134b63d3f3a3c1c69185d6ef62
+F ext/session/sqlite3session.c 26ea9b58ccd9fdfd211163bb637833d12c2beb491160e04fd415fd0519aa2685
 F ext/session/sqlite3session.h 4d1f69f1d8bfd4798e8f6431de301d17bb2e4097de2f77ca4dad494bb6c60dc0
 F ext/session/test_session.c 0b4bc954e5e411baa723e52abd46380ca428797dff39ed62c610001777a2b70f
 F ext/userauth/sqlite3userauth.h 7f3ea8c4686db8e40b0a0e7a8e0b00fac13aa7a3
@@ -2125,8 +2125,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 5dab481c101b1523b1cfde92678cbc654ea26d946bf29da372d71c1f89cbaf46 9bf4bfd68080367b58594e0d44b110b3ee9766420f648537fd7bc638dacefb72
-R 7b6d525c7f2c0f50a5d58ccf5673fd6f
+P 897e926a5eaa0eab7e09e5003e4c15c974897be298a18ae85345962dc3f410a1
+R 99b1a1d1e6fc326e3288fb4d2006c57d
 U dan
-Z 3397358e9f4504085d0516dbc6df4e33
+Z 6d17292d226b837db6fc5d0737e14243
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-897e926a5eaa0eab7e09e5003e4c15c974897be298a18ae85345962dc3f410a1
+df39fbe9ab87937beb77af353cd55602290b185e222e0a92a3ebf9a9a0b9e2e7