Add comments and an assert() to help clarify the operation of the

sqlite3VdbeList() routine used to implement EXPLAIN.

FossilOrigin-Name: e1ccdb93d79a6f7b16f1f59cc3ad78f8d02eae84

manifest

@@ -1,5 +1,8 @@
-C Minor\schanges\sto\stest\sscripts\sto\ssupport\svarious\sSQLITE_OMIT\soptions.
-D 2009-12-31T19:48:29
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA1
+
+C Add\scomments\sand\san\sassert()\sto\shelp\sclarify\sthe\soperation\sof\sthe\nsqlite3VdbeList()\sroutine\sused\sto\simplement\sEXPLAIN.
+D 2009-12-31T20:35:08
 F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0
 F Makefile.in c5827ead754ab32b9585487177c93bb00b9497b3
 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
@@ -213,7 +216,7 @@ F src/vdbe.c 5ed06318aac5d57849170a8bf39e807c22c5fedd
 F src/vdbe.h bea1f0cd530775bdb58a340265f3cf3ee920e9b2
 F src/vdbeInt.h d7ea821ac7813c9bea0fe87558c35e07b2c7c44d
 F src/vdbeapi.c fc3787eb2f5487d4cc3444de42d56f2e39d311f5
-F src/vdbeaux.c 42ed644fea54c3fbfa70af7c65456ec4ab089c77
+F src/vdbeaux.c 2e4a421bd3771ecd3b6c9a1c7abc7270a787a01b
 F src/vdbeblob.c 84f924700a7a889152aeebef77ca5f4e3875ffb4
 F src/vdbemem.c 1e16e3a16e55f4c3452834f0e041726021aa66e0
 F src/vdbetrace.c 864cef96919323482ebd9986f2132435115e9cc2
@@ -783,7 +786,14 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
 F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f
-P 6cf76c2ae25d6e58926637ecd42eed6b300b1a25
-R a3c177701c76e1795362a375d5a00fd7
-U shaneh
-Z 4cd33a23217680a7f9bd034ed143d288
+P 97f8a886b6314b044a0522a88f569798fdfb3ef9
+R ec2bfde20add495412a6ede87e046ffd
+U drh
+Z 7d63ddb9262e6acf68d6ca4997c73dd9
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v1.4.6 (GNU/Linux)
+
+iD8DBQFLPQr+oxKgR168RlERAvY/AJ9kaCj6kLbG2bTFSo/X9qosbF5uHQCff9FG
+yWtwufLA/m9wpfdsngsfSh4=
+=0KpD
+-----END PGP SIGNATURE-----

manifest.uuid

@@ -1 +1 @@
-97f8a886b6314b044a0522a88f569798fdfb3ef9
+e1ccdb93d79a6f7b16f1f59cc3ad78f8d02eae84

src/vdbeaux.c

@@ -1041,18 +1041,21 @@ void sqlite3VdbeFrameDelete(VdbeFrame *p){
 ** p->explain==2, only OP_Explain instructions are listed and these
 ** are shown in a different format.  p->explain==2 is used to implement
 ** EXPLAIN QUERY PLAN.
+**
+** When p->explain==1, first the main program is listed, then each of
+** the trigger subprograms are listed one by one.
 */
 int sqlite3VdbeList(
   Vdbe *p                   /* The VDBE */
 ){
-  int nRow;                            /* Total number of rows to return */
+  int nRow;                            /* Stop when row count reaches this */
   int nSub = 0;                        /* Number of sub-vdbes seen so far */
   SubProgram **apSub = 0;              /* Array of sub-vdbes */
-  Mem *pSub = 0;
-  sqlite3 *db = p->db;
-  int i;
-  int rc = SQLITE_OK;
-  Mem *pMem = p->pResultSet = &p->aMem[1];
+  Mem *pSub = 0;                       /* Memory cell hold array of subprogs */
+  sqlite3 *db = p->db;                 /* The database connection */
+  int i;                               /* Loop counter */
+  int rc = SQLITE_OK;                  /* Return code */
+  Mem *pMem = p->pResultSet = &p->aMem[1];  /* First Mem of result set */
 
   assert( p->explain );
   assert( p->magic==VDBE_MAGIC_RUN );
@@ -1072,12 +1075,24 @@ int sqlite3VdbeList(
     return SQLITE_ERROR;
   }
 
-  /* Figure out total number of rows that will be returned by this 
-  ** EXPLAIN program.  */
+  /* When the number of output rows reaches nRow, that means the
+  ** listing has finished and sqlite3_step() should return SQLITE_DONE.
+  ** nRow is the sum of the number of rows in the main program, plus
+  ** the sum of the number of rows in all trigger subprograms encountered
+  ** so far.  The nRow value will increase as new trigger subprograms are
+  ** encountered, but p->pc will eventually catch up to nRow.
+  */
   nRow = p->nOp;
   if( p->explain==1 ){
+    /* The first 8 memory cells are used for the result set.  So we will
+    ** commandeer the 9th cell to use as storage for an array of pointers
+    ** to trigger subprograms.  The VDBE is guaranteed to have at least 9
+    ** cells.  */
+    assert( p->nMem>9 );
     pSub = &p->aMem[9];
     if( pSub->flags&MEM_Blob ){
+      /* On the first call to sqlite3_step(), pSub will hold a NULL.  It is
+      ** initialized to a BLOB by the P4_SUBPROGRAM processing logic below */
       nSub = pSub->n/sizeof(Vdbe*);
       apSub = (SubProgram **)pSub->z;
     }
@@ -1100,8 +1115,12 @@ int sqlite3VdbeList(
     char *z;
     Op *pOp;
     if( i<p->nOp ){
+      /* The output line number is small enough that we are still in the
+      ** main program. */
       pOp = &p->aOp[i];
     }else{
+      /* We are currently listing subprograms.  Figure out which one and
+      ** pick up the appropriate opcode. */
       int j;
       i -= p->nOp;
       for(j=0; i>=apSub[j]->nOp; j++){
@@ -1123,6 +1142,11 @@ int sqlite3VdbeList(
       pMem->enc = SQLITE_UTF8;
       pMem++;
 
+      /* When an OP_Program opcode is encounter (the only opcode that has
+      ** a P4_SUBPROGRAM argument), expand the size of the array of subprograms
+      ** kept in p->aMem[9].z to hold the new program - assuming this subprogram
+      ** has not already been seen.
+      */
       if( pOp->p4type==P4_SUBPROGRAM ){
         int nByte = (nSub+1)*sizeof(SubProgram*);
         int j;