capi3ref.tcl.old

sqlite-3.4.1,嵌入式数据库.是一个功能强大的开源数据库,给学习和研发以及小型公司的发展带来了全所未有的好处.

 the second process to proceed.

 The default busy callback is NULL.

 The SQLITE_BUSY error is converted to SQLITE_IOERR_BLOCKED when
 SQLite is in the middle of a large transaction where all the
 changes will not fit into the in-memory cache.  SQLite will
 already hold a RESERVED lock on the database file, but it needs
 to promote this lock to EXCLUSIVE so that it can spill cache
 pages into the database file without harm to concurrent
 readers.  If it is unable to promote the lock, then the in-memory
 cache will be left in an inconsistent state and so the error
 code is promoted from the relatively benign SQLITE_BUSY to
 the more severe SQLITE_IOERR_BLOCKED.  This error code promotion
 forces an automatic rollback of the changes. See the
 <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
 CorruptionFollowingBusyError</a> wiki page for a discussion of why
 this is important.

 Sqlite is re-entrant, so the busy handler may start a new query. 
 (It is not clear why anyone would every want to do this, but it
 is allowed, in theory.)  But the busy handler may not close the
 database.  Closing the database from a busy handler will delete 
 data structures out from under the executing query and will 
 probably result in a coredump.

 There can only be a single busy handler defined for each database
 connection.  Setting a new busy handler clears any previous one.
 Note that calling sqlite3_busy_timeout() will also set or clear
 the busy handler.
}

api {} {
  int sqlite3_busy_timeout(sqlite3*, int ms);
} {
 This routine sets a busy handler that sleeps for a while when a
 table is locked.  The handler will sleep multiple times until 
 at least "ms" milliseconds of sleeping have been done.  After
 "ms" milliseconds of sleeping, the handler returns 0 which
 causes sqlite3_step() to return SQLITE_BUSY or SQLITE_IOERR_BLOCKED.

 Calling this routine with an argument less than or equal to zero
 turns off all busy handlers.

 There can only be a single busy handler for a particular database
 connection.  If another busy handler was defined  
 (using sqlite3_busy_handler()) prior to calling
 this routine, that other busy handler is cleared.
}

api {} {
  int sqlite3_changes(sqlite3*);
} {
 This function returns the number of database rows that were changed
 (or inserted or deleted) by the most recently completed
 INSERT, UPDATE, or DELETE
 statement.  Only changes that are directly specified by the INSERT,
 UPDATE, or DELETE statement are counted.  Auxiliary changes caused by
 triggers are not counted.  Use the sqlite3_total_changes() function
 to find the total number of changes including changes caused by triggers.

 Within the body of a trigger, the sqlite3_changes() function does work
 to report the number of rows that were changed for the most recently
 completed INSERT, UPDATE, or DELETE statement within the trigger body.

 SQLite implements the command "DELETE FROM table" without a WHERE clause
 by dropping and recreating the table.  (This is much faster than going
 through and deleting individual elements from the table.)  Because of
 this optimization, the change count for "DELETE FROM table" will be
 zero regardless of the number of elements that were originally in the
 table. To get an accurate count of the number of rows deleted, use
 "DELETE FROM table WHERE 1" instead.
}

api {} {
  int sqlite3_total_changes(sqlite3*);
} {
  This function returns the total number of database rows that have
  be modified, inserted, or deleted since the database connection was
  created using sqlite3_open().  All changes are counted, including
  changes by triggers and changes to TEMP and auxiliary databases.
  Except, changes to the SQLITE_MASTER table (caused by statements 
  such as CREATE TABLE) are not counted.  Nor are changes counted when
  an entire table is deleted using DROP TABLE.

  See also the sqlite3_changes() API.

  SQLite implements the command "DELETE FROM table" without a WHERE clause
  by dropping and recreating the table.  (This is much faster than going
  through and deleting individual elements form the table.)  Because of
  this optimization, the change count for "DELETE FROM table" will be
  zero regardless of the number of elements that were originally in the
  table. To get an accurate count of the number of rows deleted, use
  "DELETE FROM table WHERE 1" instead.
}

api {} {
  int sqlite3_close(sqlite3*);
} {
  Call this function with a pointer to a structure that was previously
  returned from sqlite3_open() or sqlite3_open16()
  and the corresponding database will by closed.

  SQLITE_OK is returned if the close is successful.  If there are
  prepared statements that have not been finalized, then SQLITE_BUSY
  is returned.  SQLITE_ERROR might be returned if the argument is not
  a valid connection pointer returned by sqlite3_open() or if the connection
  pointer has been closed previously.
}

api {} {
const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
double sqlite3_column_double(sqlite3_stmt*, int iCol);
int sqlite3_column_int(sqlite3_stmt*, int iCol);
long long int sqlite3_column_int64(sqlite3_stmt*, int iCol);
const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
int sqlite3_column_type(sqlite3_stmt*, int iCol);
#define SQLITE_INTEGER  1
#define SQLITE_FLOAT    2
#define SQLITE_TEXT     3
#define SQLITE_BLOB     4
#define SQLITE_NULL     5
} {
 These routines return information about the information
 in a single column of the current result row of a query.  In every
 case the first argument is a pointer to the SQL statement that is being
 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
 the number of bytes in that string.
 The value returned does
 not include the \\000 terminator at the end of the string.  

 The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
 but leaves the result in UTF-16 instead of UTF-8.  
 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, sqlite3_snprintf() 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 NULL pointer</td></tr>
<tr><td> NULL </td><td>    BLOB </td><td>  Result is NULL pointer</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> INTEGER </td><td> BLOB </td><td>  Same as for INTEGER->TEXT</td></tr>
<tr><td> FLOAT </td><td>   INTEGER</td><td>Convert from float to 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>

  Note that when type conversions occur, pointers returned by prior
  calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
  sqlite3_column_text16() may be invalidated. 
  Type conversions and pointer invalidations might occur
  in the following cases:

  <ul>
  <li><p>
  The initial content is a BLOB and sqlite3_column_text() 
  or sqlite3_column_text16()
  is called.  A zero-terminator might need to be added to the string.
  </p></li>
  <li><p>
  The initial content is UTF-8 text and sqlite3_column_bytes16() or
  sqlite3_column_text16() is called.  The content must be converted to UTF-16.
  </p></li>
  <li><p>
  The initial content is UTF-16 text and sqlite3_column_bytes() or
  sqlite3_column_text() is called.  The content must be converted to UTF-8.
  </p></li>
  </ul>

  Conversions between UTF-16be and UTF-16le 
  are always done in place and do
  not invalidate a prior pointer, though of course the content of the buffer
  that the prior pointer points to will have been modified.  Other kinds
  of conversion are done in place when it is possible, but sometime it is
  not possible and in those cases prior pointers are invalidated.  

  The safest and easiest to remember policy is to invoke these routines
  in one of the following ways:

  <ul>
  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
  </ul>

  In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
  or sqlite3_column_text16() first to force the result into the desired
  format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
  find the size of the result.  Do not mix call to sqlite3_column_text() or
  sqlite3_column_blob() with calls to sqlite3_column_bytes16().  And do not
  mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
}

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
 that does not return data (for example an UPDATE).

 See also sqlite3_data_count().
}

api {} {
const char *sqlite3_column_decltype(sqlite3_stmt *, int i);
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 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:

 <blockquote><pre>
 CREATE TABLE t1(c1 INTEGER);
 </pre></blockquote>

 And the following statement compiled:

 <blockquote><pre>
 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