Update comments. No changes to code. (CVS 841)

FossilOrigin-Name: f6a8706872c43cee3003b48bb427c7b74b1f89e7

5 files changed, 92 insertions, 27 deletions

diff --git a/src/encode.c b/src/encode.c
index 523a4db11..a4bea5574 100644
--- a/src/encode.c
+++ b/src/encode.c
@@ -12,10 +12,10 @@
 ** This file contains helper routines used to translate binary data into
 ** a null-terminated string (suitable for use in SQLite) and back again.
 ** These are convenience routines for use by people who want to store binary
-** data in an SQLite database.  The code in this file is used by any other
+** data in an SQLite database.  The code in this file is not used by any other
 ** part of the SQLite library.
 **
-** $Id: encode.c,v 1.4 2003/01/11 14:25:40 drh Exp $
+** $Id: encode.c,v 1.5 2003/01/19 03:59:46 drh Exp $
 */
 #include <string.h>
 
diff --git a/src/main.c b/src/main.c
index 48956db7a..23efd5546 100644
--- a/src/main.c
+++ b/src/main.c
@@ -14,7 +14,7 @@
 ** other files are for internal use by SQLite and should not be
 ** accessed by users of the library.
 **
-** $Id: main.c,v 1.108 2003/01/18 17:04:09 drh Exp $
+** $Id: main.c,v 1.109 2003/01/19 03:59:47 drh Exp $
 */
 #include "sqliteInt.h"
 #include "os.h"
@@ -39,7 +39,7 @@ typedef struct {
 **     argv[0] = "file-format" or "schema-cookie" or "table" or "index"
 **     argv[1] = table or index name or meta statement type.
 **     argv[2] = root page number for table or index.  NULL for meta.
-**     argv[3] = SQL create statement for the table or index
+**     argv[3] = SQL text for a CREATE TABLE or CREATE INDEX statement.
 **     argv[4] = "1" for temporary files, "0" for main database
 **
 */
@@ -391,7 +391,7 @@ sqlite *sqlite_open(const char *zFilename, int mode, char **pzErrMsg){
   /* If the database is in formats 1 or 2, then upgrade it to
   ** version 3.  This will reconstruct all indices.  If the
   ** upgrade fails for any reason (ex: out of disk space, database
-  ** is read only, interrupt receive, etc.) then refuse to open.
+  ** is read only, interrupt received, etc.) then refuse to open.
   */
   if( rc==SQLITE_OK && db->file_format<3 ){
     char *zErr = 0;
@@ -786,7 +786,8 @@ void sqlite_freemem(void *p){ free(p); }
 
 /*
 ** Windows systems need functions to call to return the sqlite_version
-** and sqlite_encoding strings.
+** and sqlite_encoding strings since they are unable to access constants
+** within DLLs.
 */
 const char *sqlite_libversion(void){ return sqlite_version; }
 const char *sqlite_libencoding(void){ return sqlite_encoding; }
diff --git a/src/printf.c b/src/printf.c
index af703f3f9..1ef6f42ce 100644
--- a/src/printf.c
+++ b/src/printf.c
@@ -3,8 +3,8 @@
 ** the public domain.  The original comments are included here for
 ** completeness.  They are slightly out-of-date.
 **
-** The following modules is an enhanced replacement for the "printf" programs
-** found in the standard library.  The following enhancements are
+** The following modules is an enhanced replacement for the "printf" subroutines
+** found in the standard C library.  The following enhancements are
 ** supported:
 **
 **      +  Additional functions.  The standard set of "printf" functions
diff --git a/src/select.c b/src/select.c
index 5a72a1a44..29b1f9e3a 100644
--- a/src/select.c
+++ b/src/select.c
@@ -12,7 +12,7 @@
 ** This file contains C code routines that are called by the parser
 ** to handle SELECT statements in SQLite.
 **
-** $Id: select.c,v 1.122 2003/01/18 20:11:07 drh Exp $
+** $Id: select.c,v 1.123 2003/01/19 03:59:47 drh Exp $
 */
 #include "sqliteInt.h"
 
@@ -180,7 +180,7 @@ static void addWhereTerm(
 /*
 ** Set the EP_FromJoin property on all terms of the given expression.
 **
-** The EP_FromJoin property is used at on terms of an expression to tell
+** The EP_FromJoin property is used on terms of an expression to tell
 ** the LEFT OUTER JOIN processing logic that this term is part of the
 ** join restriction specified in the ON or USING clause and not a part
 ** of the more general WHERE clause.  These terms are moved over to the
@@ -677,6 +677,17 @@ static void generateSortTail(
 /*
 ** Generate code that will tell the VDBE the datatypes of
 ** columns in the result set.
+**
+** This routine only generates code if the "PRAGMA show_datatypes=on"
+** has been executed.  The datatypes are reported out in the azCol
+** parameter to the callback function.  The first N azCol[] entries
+** are the names of the columns, and the second N entries are the
+** datatypes for the columns.
+**
+** The "datatype" for a result that is a column of a type is the
+** datatype definition extracted from the CREATE TABLE statement.
+** The datatype for an expression is either TEXT or NUMERIC.  The
+** datatype for a ROWID field is INTEGER.
 */
 static void generateColumnTypes(
   Parse *pParse,      /* Parser context */
@@ -1187,7 +1198,19 @@ Vdbe *sqliteGetVdbe(Parse *pParse){
 **
 ** Examples:
 **
-**    SELECT a,b
+**     CREATE TABLE one(a INTEGER, b TEXT);
+**     CREATE TABLE two(c VARCHAR(5), d FLOAT);
+**
+**     SELECT b, b FROM one UNION SELECT d, c FROM two ORDER BY 1, 2;
+**
+** The primary sort key will use SQLITE_SO_NUM because the "d" in
+** the second SELECT is numeric.  The 1st column of the first SELECT
+** is text but that does not matter because a numeric always overrides
+** a text.
+**
+** The secondary key will use the SQLITE_SO_TEXT sort order because
+** both the (second) "b" in the first SELECT and the "c" in the second
+** SELECT have a datatype of text.
 */ 
 static void multiSelectSortOrder(Select *p, ExprList *pOrderBy){
   int i;
@@ -1215,8 +1238,31 @@ static void multiSelectSortOrder(Select *p, ExprList *pOrderBy){
 ** This routine is called to process a query that is really the union
 ** or intersection of two or more separate queries.
 **
-** "p" points to the right-most of the two queries.  The results should
-** be stored in eDest with parameter iParm.
+** "p" points to the right-most of the two queries.  the query on the
+** left is p->pPrior.  The left query could also be a compound query
+** in which case this routine will be called recursively. 
+**
+** The results of the total query are to be written into a destination
+** of type eDest with parameter iParm.
+**
+** Example 1:  Consider a three-way compound SQL statement.
+**
+**     SELECT a FROM t1 UNION SELECT b FROM t2 UNION SELECT c FROM t3
+**
+** This statement is parsed up as follows:
+**
+**     SELECT c FROM t3
+**      |
+**      `----->  SELECT b FROM t2
+**                |
+**                `------>  SELECT c FROM t1
+**
+** The arrows in the diagram above represent the Select.pPrior pointer.
+** So if this routine is called with p equal to the t3 query, then
+** pPrior will be the t2 query.  p->op will be TK_UNION in this case.
+**
+** Notice that because of the way SQLite parses compound SELECTs, the
+** individual selects always group from left to right.
 */
 static int multiSelect(Parse *pParse, Select *p, int eDest, int iParm){
   int rc;             /* Success code from a subroutine */
@@ -1695,7 +1741,7 @@ static int flattenSubquery(
 ** Analyze the SELECT statement passed in as an argument to see if it
 ** is a simple min() or max() query.  If it is and this query can be
 ** satisfied using a single seek to the beginning or end of an index,
-** then generate the code for this SELECT return 1.  If this is not a 
+** then generate the code for this SELECT and return 1.  If this is not a 
 ** simple min() or max() query, then return 0;
 **
 ** A simply min() or max() query looks like this:
@@ -1826,6 +1872,10 @@ static int simpleMinMaxQuery(Parse *pParse, Select *p, int eDest, int iParm){
 **
 **     SRT_Table       Store results in temporary table iParm
 **
+** The table above is incomplete.  Additional eDist value have be added
+** since this comment was written.  See the selectInnerLoop() function for
+** a complete listing of the allowed values of eDest and their meanings.
+**
 ** This routine returns the number of errors.  If any errors are
 ** encountered, then an appropriate error message is left in
 ** pParse->zErrMsg.
@@ -1839,12 +1889,26 @@ static int simpleMinMaxQuery(Parse *pParse, Select *p, int eDest, int iParm){
 ** change the parent query from a non-aggregate to an aggregate query.
 ** For that reason, the pParentAgg flag is passed as a pointer, so it
 ** can be changed.
+**
+** Example 1:   The meaning of the pParent parameter.
+**
+**    SELECT * FROM t1 JOIN (SELECT x, count(*) FROM t2) JOIN t3;
+**    \                      \_______ subquery _______/        /
+**     \                                                      /
+**      \____________________ outer query ___________________/
+**
+** This routine is called for the outer query first.   For that call,
+** pParent will be NULL.  During the processing of the outer query, this 
+** routine is called recursively to handle the subquery.  For the recursive
+** call, pParent will point to the outer query.  Because the subquery is
+** the second element in a three-way join, the parentTab parameter will
+** be 1 (the 2nd value of a 0-indexed array.)
 */
 int sqliteSelect(
   Parse *pParse,         /* The parser context */
   Select *p,             /* The SELECT statement being coded. */
-  int eDest,             /* One of: SRT_Callback Mem Set Union Except */
-  int iParm,             /* Save result in this memory location, if >=0 */
+  int eDest,             /* How to dispose of the results */
+  int iParm,             /* A parameter used by the eDest disposal method */
   Select *pParent,       /* Another SELECT for which this is a sub-query */
   int parentTab,         /* Index in pParent->pSrc of this query */
   int *pParentAgg        /* True if pParent uses aggregate functions */
@@ -1895,9 +1959,9 @@ int sqliteSelect(
   */
   if( pParse->nErr>0 ) goto select_end;
 
-  /* Look up every table in the table list and create an appropriate
-  ** columnlist in pEList if there isn't one already.  (The parser leaves
-  ** a NULL in the p->pEList if the SQL said "SELECT * FROM ...")
+  /* Expand any "*" terms in the result set.  (For example the "*" in
+  ** "SELECT * FROM t1")  The fillInColumnlist() routine also does some
+  ** other housekeeping - see the header comment for details.
   */
   if( fillInColumnList(pParse, p) ){
     goto select_end;
@@ -2024,8 +2088,8 @@ int sqliteSelect(
   v = sqliteGetVdbe(pParse);
   if( v==0 ) goto select_end;
 
-  /* Identify column names if we will be using in the callback.  This
-  ** step is skipped if the output is going to a table or a memory cell.
+  /* Identify column names if we will be using them in a callback.  This
+  ** step is skipped if the output is going to some other destination.
   */
   if( eDest==SRT_Callback ){
     generateColumnNames(pParse, p->base, pTabList, pEList);
@@ -2076,8 +2140,9 @@ int sqliteSelect(
     return rc;
   }
 
-  /* Identify column types if we will be using in the callback.  This
-  ** step is skipped if the output is going to a table or a memory cell.
+  /* Identify column types if we will be using a callback.  This
+  ** step is skipped if the output is going to a destination other
+  ** than a callback.
   */
   if( eDest==SRT_Callback ){
     generateColumnTypes(pParse, p->base, pTabList, pEList);
@@ -2254,7 +2319,6 @@ int sqliteSelect(
   ** successful coding of the SELECT.
   */
 select_end:
-  /* pParse->nTab = base; */
   sqliteAggregateInfoReset(pParse);
   return rc;
 }
diff --git a/src/vdbe.c b/src/vdbe.c
index ba3fcca82..ac92fa044 100644
--- a/src/vdbe.c
+++ b/src/vdbe.c
@@ -36,7 +36,7 @@
 ** in this file for details.  If in doubt, do not deviate from existing
 ** commenting and indentation practices when changing or adding code.
 **
-** $Id: vdbe.c,v 1.198 2003/01/16 13:42:43 drh Exp $
+** $Id: vdbe.c,v 1.199 2003/01/19 03:59:47 drh Exp $
 */
 #include "sqliteInt.h"
 #include <ctype.h>
@@ -1759,8 +1759,8 @@ case OP_Callback: {
 **
 ** Invoke the callback function once with the 2nd argument (the
 ** number of columns) equal to P1 and with the 4th argument (the
-** names of the columns) set according to prior OP_ColumnName and
-** OP_ColumnCount instructions.  This is all like the regular
+** names of the columns) set according to prior OP_ColumnName
+** instructions.  This is all like the regular
 ** OP_Callback or OP_SortCallback opcodes.  But the 3rd argument
 ** which normally contains a pointer to an array of pointers to
 ** data is NULL.