SQLite

set rcsid {$Id: capi3ref.tcl,v 1.59 2007/05/15 14:17:25 drh Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}
puts {
<h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {

  int sqlite3_bind_null(sqlite3_stmt*, int);
  int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
  int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
  #define SQLITE_STATIC      ((void(*)(void *))0)
  #define SQLITE_TRANSIENT   ((void(*)(void *))-1)
} {
 In the SQL strings input to sqlite3_prepare_v2() and sqlite3_prepare16_v2(),
 one or more literals can be replace by a parameter "?" or "?NNN"
 or ":AAA" or "@AAA" or "\$VVV" where NNN is an integer literal,
 AAA is an alphanumeric identifier and VVV is a variable name according
 to the syntax rules of the TCL programming language.
 The values of these parameters (also called "host parameter names")
 can be set using the sqlite3_bind_*() routines.

 The first argument to the sqlite3_bind_*() routines always is a pointer
 to the sqlite3_stmt structure returned from sqlite3_prepare_v2().  The second
 argument is the index of the parameter to be set.  The first parameter has
 an index of 1. When the same named parameter is used more than once, second
 and subsequent
 occurrences have the same index as the first occurrence.  The index for
 named parameters can be looked up using the
 sqlite3_bind_parameter_name() API if desired.  The index for "?NNN"
 parametes is the value of NNN.  The NNN value must be between 1 and 999.


 The third argument is the value to bind to the parameter.

 In those
 routines that have a fourth argument, its value is the number of bytes
 in the parameter.  To be clear: the value is the number of bytes in the
 string, not the number of characters.  The number

}

api {} {
  const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int n);
} {
  Return the name of the n-th parameter in the precompiled statement.
  Parameters of the form ":AAA" or "@AAA" or "\$VVV" have a name which is the
  string ":AAA" or "@AAA" or "\$VVV".  
  In other words, the initial ":" or "$" or "@"
  is included as part of the name.
  Parameters of the form "?" or "?NNN" have no name.

  The first bound parameter has an index of 1, not 0.

  If the value n is out of range or if the n-th parameter is nameless,
  then NULL is returned.  The returned string is always in the
  UTF-8 encoding even if the named parameter was originally specified
  as UTF-16 in sqlite3_prepare16_v2().
}

api {} {
  int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
} {
  Return the index of the parameter with the given name.
  The name must match exactly.

 executed (the sqlite_stmt* that was returned from sqlite3_prepare_v2()) and
 the second argument is the index of the column for which information 
 should be returned.  iCol is zero-indexed.  The left-most column has 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.

 The sqlite3_column_type() routine returns the initial data type
 of the result column.  The returned value is one of SQLITE_INTEGER,
 SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL.  The value
 returned by sqlite3_column_type() is only meaningful if no type
 conversions have occurred as described below.  After a type conversion,
 the value returned by sqlite3_column_type() is undefined.  Future
 versions of SQLite may change the behavior of sqlite3_column_type()
 following a type conversion.

 If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 
 routine returns the number of bytes in that BLOB or string.
 If the result is a UTF-16 string, then sqlite3_column_bytes() converts
 the string to UTF-8 and then returns the number of bytes.
 If the result is a numeric value then sqlite3_column_bytes() uses
 sqlite3_snprintf() to convert that value to a UTF-8 string and returns