Add documentation for new APIs. (CVS 3076)

FossilOrigin-Name: 84c2a5c4d753d1e39136ac7e80ac816442af0a49

manifest

@@ -1,5 +1,5 @@
-C More\scomments\son\sthe\sunix\slocking\scode.\s\sTicket\s#1672.\s(CVS\s3075)
+C Add\sdocumentation\sfor\snew\sAPIs.\s(CVS\s3076)
-D 2006-02-10T13:11:32
+D 2006-02-10T13:14:21
 F Makefile.in 5d8dff443383918b700e495de42ec65bc1c8865b
 F Makefile.linux-gcc 74ba0eadf88748a9ce3fd03d2a3ede2e6715baec
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -308,7 +308,7 @@ F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0
 F www/autoinc.tcl b357f5ba954b046ee35392ce0f884a2fcfcdea06
 F www/c_interface.tcl b51b08591554c16a0c3ef718364a508ac25abc7e
 F www/capi3.tcl 7a7cc225fe02eb7ab861a6019b08baa0014409e1
-F www/capi3ref.tcl 458d541139b84155e518781dcb9ebe9f57fe5cbf
+F www/capi3ref.tcl 16195e218ebc5fc5ee3ca859f66b707ed8e9eea1
 F www/changes.tcl c36d331b25a3b193845c05a6fa3f914899634940
 F www/common.tcl 14d121c28532ad20c3e349caa4db708b0b822083
 F www/compile.tcl 276546d7eb445add5a867193bbd80f6919a6b084
@@ -352,7 +352,7 @@ F www/tclsqlite.tcl bb0d1357328a42b1993d78573e587c6dcbc964b9
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl a99cf5f6d8bd4d5537584a2b342f0fb9fa601d8b
 F www/whentouse.tcl 97e2b5cd296f7d8057e11f44427dea8a4c2db513
-P 424ce5ecd0aa9860afb73180e4d09987f3a9300a
+P 4b6f5688843ebe39f6bd3e863666a44d486fbe0f
-R e847d3d7d8d22728ba3f4d78b38cd20a
+R e16ab060e2ea8f3c75745aba1282f4f4
-U drh
+U danielk1977
-Z 206d0335c5f7ebb9928e90a31eabfd6a
+Z a2ce105beec66212c267fbbe4c9ef5e8

manifest.uuid

@@ -1 +1 @@
-4b6f5688843ebe39f6bd3e863666a44d486fbe0f
+84c2a5c4d753d1e39136ac7e80ac816442af0a49

www/capi3ref.tcl

@@ -1,4 +1,4 @@
-set rcsid {$Id: capi3ref.tcl,v 1.32 2006/02/09 18:35:30 drh Exp $}
+set rcsid {$Id: capi3ref.tcl,v 1.33 2006/02/10 13:14:21 danielk1977 Exp $}
 source common.tcl
 header {C/C++ Interface For SQLite Version 3}
 puts {
@@ -366,11 +366,10 @@ const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
  The first argument is a prepared SQL statement. If this statement
  is a SELECT statement, the Nth column of the returned result set 
  of the SELECT is a table column then the declared type of the table
- column is returned. If the Nth column of the result set is not at table
+ column is returned. If the Nth column of the result set is not a table
  column, then a NULL pointer is returned. The returned string is 
  UTF-8 encoded for sqlite3_column_decltype() and UTF-16 encoded
- for sqlite3_column_decltype16().
+ for sqlite3_column_decltype16(). For example, in the database schema:
- For example, in the database schema:
 
  <blockquote><pre>
  CREATE TABLE t1(c1 INTEGER);
@@ -379,12 +378,140 @@ const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
  And the following statement compiled:
 
  <blockquote><pre>
- SELECT c1 + 1, 0 FROM t1;
+ SELECT c1 + 1, c1 FROM t1;
  </pre></blockquote>
 
  Then this routine would return the string "INTEGER" for the second
  result column (i==1), and a NULL pointer for the first result column
  (i==0).
+
+ If the following statements were compiled then this routine would
+ return "INTEGER" for the first (only) result column.
+
+ <blockquote><pre>
+ SELECT (SELECT c1) FROM t1;
+ SELECT (SELECT c1 FROM t1);
+ SELECT c1 FROM (SELECT c1 FROM t1);
+ SELECT * FROM (SELECT c1 FROM t1);
+ SELECT * FROM (SELECT * FROM t1);
+ </pre></blockquote>
+}
+
+api {} {
+  int sqlite3_table_column_metadata(
+    sqlite3 *db,                /* Connection handle */
+    const char *zDbName,        /* Database name or NULL */
+    const char *zTableName,     /* Table name */
+    const char *zColumnName,    /* Column name */
+    char const **pzDataType,    /* OUTPUT: Declared data type */
+    char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
+    int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
+    int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
+    int *pAutoinc               /* OUTPUT: True if colums is auto-increment */
+  );
+} {
+ This routine is used to obtain meta information about a specific column of a
+ specific database table accessible using the connection handle passed as the
+ first function argument.
+
+ The column is identified by the second, third and fourth parameters to 
+ this function. The second parameter is either the name of the database
+ (i.e. "main", "temp" or an attached database) containing the specified
+ table or NULL. If it is NULL, then all attached databases are searched
+ for the table using the same algorithm as the database engine uses to 
+ resolve unqualified table references.
+
+ The third and fourth parameters to this function are the table and column 
+ name of the desired column, respectively. Neither of these parameters 
+ may be NULL.
+
+ Meta information is returned by writing to the memory locations passed as
+ the 5th and subsequent parameters to this function. Any of these 
+ arguments may be NULL, in which case the corresponding element of meta 
+ information is ommitted.
+
+<pre>
+ Parameter     Output Type      Description
+ -----------------------------------
+   5th         const char*      Declared data type 
+   6th         const char*      Name of the columns default collation sequence 
+   7th         int              True if the column has a NOT NULL constraint
+   8th         int              True if the column is part of the PRIMARY KEY
+   9th         int              True if the column is AUTOINCREMENT
+</pre>
+
+ The memory pointed to by the character pointers returned for the 
+ declaration type and collation sequence is valid only until the next 
+ call to any sqlite API function.
+
+ This function may load one or more schemas from database files. If an
+ error occurs during this process, or if the requested table or column
+ cannot be found, an SQLITE error code is returned and an error message
+ left in the database handle (to be retrieved using sqlite3_errmsg()).
+ Specifying an SQL view instead of a table as the third argument is also
+ considered an error.
+
+ If the specified column is "rowid", "oid" or "_rowid_" and an 
+ INTEGER PRIMARY KEY column has been explicitly declared, then the output 
+ parameters are set for the explicitly declared column. If there is no
+ explicitly declared IPK column, then the data-type is "INTEGER", the
+ collation sequence "BINARY" and the primary-key flag is set. Both
+ the not-null and auto-increment flags are clear.
+
+ This API is only available if the library was compiled with the
+ SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
+}
+
+api {} {
+const char *sqlite3_column_database_name(sqlite3_stmt *pStmt, int N);
+const void *sqlite3_column_database_name16(sqlite3_stmt *pStmt, int N);
+} {
+If the Nth column returned by statement pStmt is a column reference,
+these functions may be used to access the name of the database (either 
+"main", "temp" or the name of an attached database) that contains
+the column. If the Nth column is not a column reference, NULL is
+returned.
+
+See the description of function sqlite3_column_decltype() for a
+description of exactly which expressions are considered column references.
+
+Function sqlite3_column_database_name() returns a pointer to a UTF-8
+encoded string. sqlite3_column_database_name16() returns a pointer
+to a UTF-16 encoded string. 
+}
+
+api {} {
+const char *sqlite3_column_origin_name(sqlite3_stmt *pStmt, int N);
+const void *sqlite3_column_origin_name16(sqlite3_stmt *pStmt, int N);
+} {
+If the Nth column returned by statement pStmt is a column reference,
+these functions may be used to access the schema name of the referenced 
+column in the database schema. If the Nth column is not a column 
+reference, NULL is returned.
+
+See the description of function sqlite3_column_decltype() for a
+description of exactly which expressions are considered column references.
+
+Function sqlite3_column_origin_name() returns a pointer to a UTF-8
+encoded string. sqlite3_column_origin_name16() returns a pointer
+to a UTF-16 encoded string. 
+}
+
+api {} {
+const char *sqlite3_column_table_name(sqlite3_stmt *pStmt, int N);
+const void *sqlite3_column_table_name16(sqlite3_stmt *pStmt, int N);
+} {
+If the Nth column returned by statement pStmt is a column reference, 
+these functions may be used to access the name of the table that 
+contains the column.  If the Nth column is not a column reference, 
+NULL is returned.
+
+See the description of function sqlite3_column_decltype() for a
+description of exactly which expressions are considered column references.
+
+Function sqlite3_column_table_name() returns a pointer to a UTF-8
+encoded string. sqlite3_column_table_name16() returns a pointer
+to a UTF-16 encoded string. 
 }
 
 api {} {