/ Check-in [814c58d4]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Updates to the C-language API documents for version 3.0. (CVS 1840)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:814c58d470922d77cfcc6c4d5d26c1ec4c28ca60
User & Date: drh 2004-07-21 14:07:58
Context
2004-07-21
14:54
Update the TCL API documentation. (CVS 1841) check-in: df306ad9 user: drh tags: trunk
14:07
Updates to the C-language API documents for version 3.0. (CVS 1840) check-in: 814c58d4 user: drh tags: trunk
02:53
Minor coding enhancements. (CVS 1839) check-in: 65c3af74 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to www/capi3ref.tcl.

1
2
3
4
5
6
7
8
...
222
223
224
225
226
227
228
229











230
231
232
233
234
235
236

237
238
239
240
241
242
243
244
...
247
248
249
250
251
252
253
254
255

256
257
258
259
260
261
262
...
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
...
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
...
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
...
906
907
908
909
910
911
912
913





914
915
916
917
918
919
920
...
978
979
980
981
982
983
984
985
986
987



988
989
990
991
992
993
994
set rcsid {$Id: capi3ref.tcl,v 1.5 2004/06/19 08:18:27 danielk1977 Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}
puts {
<h2>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {
................................................................................
 case the first parameter is a pointer to the SQL statement that is being
 executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and
 the second argument is the index of the column for which information 
 should be returned.  iCol is zero-indexed.  The left-most column as an
 index of 0.

 If the SQL statement is not currently point to a valid row, or if the
 the colulmn index is out of range, the result is undefined.












 These routines attempt to convert the value where appropriate.  For
 example, if the internal representation is FLOAT and a text result
 is requested, sprintf() is used internally to do the conversion
 automatically.  The following table details the conversions that
 are applied:


 <table broder=1>
<tr><th>Internal Type</th><th>Requested Type</th><th>Conversion</th></tr>
<tr><td> NULL    </td><td> INTEGER</td><td>Result is 0</td></tr>
<tr><td> NULL </td><td>    FLOAT </td><td> Result is 0.0</td></tr>
<tr><td> NULL </td><td>    TEXT </td><td>  Result is an empty string</td></tr>
<tr><td> NULL </td><td>    BLOB </td><td>  Result is a zero-length BLOB</td></tr>
<tr><td> INTEGER </td><td> FLOAT </td><td> Convert from integer to float</td></tr>
<tr><td> INTEGER </td><td> TEXT </td><td>  ASCII rendering of the integer</td></tr>
................................................................................
<tr><td> FLOAT </td><td>   TEXT </td><td>  ASCII rendering of the float</td></tr>
<tr><td> FLOAT </td><td>   BLOB </td><td>  Same as FLOAT->TEXT</td></tr>
<tr><td> TEXT </td><td>    INTEGER</td><td>Use atoi()</td></tr>
<tr><td> TEXT </td><td>    FLOAT </td><td> Use atof()</td></tr>
<tr><td> TEXT </td><td>    BLOB </td><td>  No change</td></tr>
<tr><td> BLOB </td><td>    INTEGER</td><td>Convert to TEXT then use atoi()</td></tr>
<tr><td> BLOB </td><td>    FLOAT </td><td> Convert to TEXT then use atof()</td></tr>
<tr><td> BLOB </td><td>    TEXT </td><td>  Add a \000 terminator if needed</td></tr>
</table>

}

api {} {
int sqlite3_column_count(sqlite3_stmt *pStmt);
} {
 Return the number of columns in the result set returned by the prepared
 SQL statement. This routine returns 0 if pStmt is an SQL statement
................................................................................
 options that are useful for constructing SQL statements.

 The strings returned by these routines should be freed by calling
 sqlite3_free().

 All of the usual printf formatting options apply.  In addition, there
 is a "%q" option.  %q works like %s in that it substitutes a null-terminated
 string from the argument list.  But %q also doubles every '\'' character.
 %q is designed for use inside a string literal.  By doubling each '\''
 character it escapes that character and allows it to be inserted into
 the string.

 For example, so some string variable contains text as follows:

 <blockquote><pre>
  char *zText = "It's a happy day!";
................................................................................
 One can use this text in an SQL statement as follows:

 <blockquote><pre>
  sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",
       callback1, 0, 0, zText);
  </pre></blockquote>

 Because the %q format string is used, the '\'' character in zText
 is escaped and the SQL generated is as follows:

 <blockquote><pre>
  INSERT INTO table1 VALUES('It''s a happy day!')
 </pre></blockquote>

 This is correct.  Had we used %s instead of %q, the generated SQL
................................................................................
#define SQLITE_DETACH               25   /* Database Name   NULL            */

#define SQLITE_DENY   1   /* Abort the SQL statement with an error */
#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
} {
 This routine registers a callback with the SQLite library.  The
 callback is invoked (at compile-time, not at run-time) for each
 attempt to access a column of a table in the database.  The callback
 returns SQLITE_OK if access is allowed, SQLITE_DENY if the entire
 SQL statement should be aborted with an error and SQLITE_IGNORE
 if the column should be treated as a NULL value.

 The second parameter to the access authorization function above will
 be one of the values below.  These values signify what kind of operation
 is to be authorized.  The 3rd and 4th parameters to the authorization
 function will be parameters or NULL depending on which of the following
................................................................................
 codes is used as the second parameter.  The 5th parameter is the name
 of the database ("main", "temp", etc.) if applicable.  The 6th parameter
 is the name of the inner-most trigger or view that is responsible for
 the access attempt or NULL if this access attempt is directly from 
 input SQL code.

 The return value of the authorization function should be one of the
 constants SQLITE_DENY or SQLITE_IGNORE.





}

api {} {
int sqlite3_step(sqlite3_stmt*);
} {
 After an SQL query has been prepared with a call to either
 sqlite3_prepare() or sqlite3_prepare16(), then this function must be
................................................................................
const void *sqlite3_value_text16be(sqlite3_value*);
const void *sqlite3_value_text16le(sqlite3_value*);
int sqlite3_value_type(sqlite3_value*);
} {
 This group of routines returns information about parameters to
 a user-defined function.  Function implementations use these routines
 to access their parameters.  These routines are the same as the
 sqlite3_column_* routines except that these routines take a single
 sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
 column number.



}

set n 0
set i 0
foreach item $apilist {
  set namelist [lindex $item 0]
  foreach name $namelist {
|







 







|
>
>
>
>
>
>
>
>
>
>
>







>
|







 







|

>







 







|
|







 







|







 







|
|







 







|
>
>
>
>
>







 







|


>
>
>







1
2
3
4
5
6
7
8
...
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
...
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
...
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
...
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
...
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
...
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
...
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
set rcsid {$Id: capi3ref.tcl,v 1.6 2004/07/21 14:07:58 drh Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}
puts {
<h2>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {
................................................................................
 case the first parameter is a pointer to the SQL statement that is being
 executed (the sqlite_stmt* that was returned from sqlite3_prepare()) and
 the second argument is the index of the column for which information 
 should be returned.  iCol is zero-indexed.  The left-most column as an
 index of 0.

 If the SQL statement is not currently point to a valid row, or if the
 the column index is out of range, the result is undefined.

 If the result is a BLOB then the sqlite3_column_bytes() routine returns
 the number of bytes in that BLOB.  No type conversions occur.
 If the result is a string (or a number since a number can be converted
 into a string) then sqlite3_column_bytes() converts
 the value into a UTF-8 string and returns
 the number of bytes in the resulting string.  The value returned does
 not include the \\000 terminator at the end of the string.  The
 sqlite3_column_bytes16() routine converts the value into a UTF-16
 encoding and returns the number of bytes (not characters) in the
 resulting string.  The \\u0000 terminator is not included in this count.

 These routines attempt to convert the value where appropriate.  For
 example, if the internal representation is FLOAT and a text result
 is requested, sprintf() is used internally to do the conversion
 automatically.  The following table details the conversions that
 are applied:

<blockquote>
<table border="1">
<tr><th>Internal Type</th><th>Requested Type</th><th>Conversion</th></tr>
<tr><td> NULL    </td><td> INTEGER</td><td>Result is 0</td></tr>
<tr><td> NULL </td><td>    FLOAT </td><td> Result is 0.0</td></tr>
<tr><td> NULL </td><td>    TEXT </td><td>  Result is an empty string</td></tr>
<tr><td> NULL </td><td>    BLOB </td><td>  Result is a zero-length BLOB</td></tr>
<tr><td> INTEGER </td><td> FLOAT </td><td> Convert from integer to float</td></tr>
<tr><td> INTEGER </td><td> TEXT </td><td>  ASCII rendering of the integer</td></tr>
................................................................................
<tr><td> FLOAT </td><td>   TEXT </td><td>  ASCII rendering of the float</td></tr>
<tr><td> FLOAT </td><td>   BLOB </td><td>  Same as FLOAT->TEXT</td></tr>
<tr><td> TEXT </td><td>    INTEGER</td><td>Use atoi()</td></tr>
<tr><td> TEXT </td><td>    FLOAT </td><td> Use atof()</td></tr>
<tr><td> TEXT </td><td>    BLOB </td><td>  No change</td></tr>
<tr><td> BLOB </td><td>    INTEGER</td><td>Convert to TEXT then use atoi()</td></tr>
<tr><td> BLOB </td><td>    FLOAT </td><td> Convert to TEXT then use atof()</td></tr>
<tr><td> BLOB </td><td>    TEXT </td><td>  Add a \\000 terminator if needed</td></tr>
</table>
</blockquote>
}

api {} {
int sqlite3_column_count(sqlite3_stmt *pStmt);
} {
 Return the number of columns in the result set returned by the prepared
 SQL statement. This routine returns 0 if pStmt is an SQL statement
................................................................................
 options that are useful for constructing SQL statements.

 The strings returned by these routines should be freed by calling
 sqlite3_free().

 All of the usual printf formatting options apply.  In addition, there
 is a "%q" option.  %q works like %s in that it substitutes a null-terminated
 string from the argument list.  But %q also doubles every '\\'' character.
 %q is designed for use inside a string literal.  By doubling each '\\''
 character it escapes that character and allows it to be inserted into
 the string.

 For example, so some string variable contains text as follows:

 <blockquote><pre>
  char *zText = "It's a happy day!";
................................................................................
 One can use this text in an SQL statement as follows:

 <blockquote><pre>
  sqlite3_exec_printf(db, "INSERT INTO table VALUES('%q')",
       callback1, 0, 0, zText);
  </pre></blockquote>

 Because the %q format string is used, the '\\'' character in zText
 is escaped and the SQL generated is as follows:

 <blockquote><pre>
  INSERT INTO table1 VALUES('It''s a happy day!')
 </pre></blockquote>

 This is correct.  Had we used %s instead of %q, the generated SQL
................................................................................
#define SQLITE_DETACH               25   /* Database Name   NULL            */

#define SQLITE_DENY   1   /* Abort the SQL statement with an error */
#define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
} {
 This routine registers a callback with the SQLite library.  The
 callback is invoked (at compile-time, not at run-time) for each
 attempt to access a column of a table in the database.  The callback should
 return SQLITE_OK if access is allowed, SQLITE_DENY if the entire
 SQL statement should be aborted with an error and SQLITE_IGNORE
 if the column should be treated as a NULL value.

 The second parameter to the access authorization function above will
 be one of the values below.  These values signify what kind of operation
 is to be authorized.  The 3rd and 4th parameters to the authorization
 function will be parameters or NULL depending on which of the following
................................................................................
 codes is used as the second parameter.  The 5th parameter is the name
 of the database ("main", "temp", etc.) if applicable.  The 6th parameter
 is the name of the inner-most trigger or view that is responsible for
 the access attempt or NULL if this access attempt is directly from 
 input SQL code.

 The return value of the authorization function should be one of the
 constants SQLITE_OK, SQLITE_DENY, or SQLITE_IGNORE.

 The intent of this routine is to allow applications to safely execute
 user-entered SQL.  An appropriate callback can deny the user-entered
 SQL access certain operations (ex: anything that changes the database)
 or to deny access to certain tables or columns within the database.
}

api {} {
int sqlite3_step(sqlite3_stmt*);
} {
 After an SQL query has been prepared with a call to either
 sqlite3_prepare() or sqlite3_prepare16(), then this function must be
................................................................................
const void *sqlite3_value_text16be(sqlite3_value*);
const void *sqlite3_value_text16le(sqlite3_value*);
int sqlite3_value_type(sqlite3_value*);
} {
 This group of routines returns information about parameters to
 a user-defined function.  Function implementations use these routines
 to access their parameters.  These routines are the same as the
 sqlite3_column_... routines except that these routines take a single
 sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
 column number.

 See the documentation under sqlite3_column_blob for additional
 information.
}

set n 0
set i 0
foreach item $apilist {
  set namelist [lindex $item 0]
  foreach name $namelist {