From: danielk1977 Date: Fri, 10 Feb 2006 13:14:20 +0000 (+0000) Subject: Add documentation for new APIs. (CVS 3076) X-Git-Tag: version-3.6.10~3091 X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=ad2dccde5f160dd58c2238febc735763bf9da8a2;p=thirdparty%2Fsqlite.git Add documentation for new APIs. (CVS 3076) FossilOrigin-Name: 84c2a5c4d753d1e39136ac7e80ac816442af0a49 --- diff --git a/manifest b/manifest index 5ee284ac5a..d19e87fcf7 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C More\scomments\son\sthe\sunix\slocking\scode.\s\sTicket\s#1672.\s(CVS\s3075) -D 2006-02-10T13:11:32 +C Add\sdocumentation\sfor\snew\sAPIs.\s(CVS\s3076) +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 -R e847d3d7d8d22728ba3f4d78b38cd20a -U drh -Z 206d0335c5f7ebb9928e90a31eabfd6a +P 4b6f5688843ebe39f6bd3e863666a44d486fbe0f +R e16ab060e2ea8f3c75745aba1282f4f4 +U danielk1977 +Z a2ce105beec66212c267fbbe4c9ef5e8 diff --git a/manifest.uuid b/manifest.uuid index a2c1ee27c2..f6c2a947d8 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -4b6f5688843ebe39f6bd3e863666a44d486fbe0f \ No newline at end of file +84c2a5c4d753d1e39136ac7e80ac816442af0a49 \ No newline at end of file diff --git a/www/capi3ref.tcl b/www/capi3ref.tcl index 4841f94107..78e154626c 100644 --- a/www/capi3ref.tcl +++ b/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 example, in the database schema: + for sqlite3_column_decltype16(). For example, in the database schema: 
  CREATE TABLE t1(c1 INTEGER);
@@ -379,12 +378,140 @@ const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
  And the following statement compiled:
 
  
- SELECT c1 + 1, 0 FROM t1;
+ SELECT c1 + 1, c1 FROM t1;
  

 
  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.
+
+ 
+ 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);
+ 

+}
+
+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.
+
+
+ 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
+

+
+ 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 {} {