I would appreciate any donations. Wishlist or send e-mail type donations to maekawa AT daemon-systems.org.

Thank you.


SQLITE3_COLUMN_BLOB(3)     Library Functions Manual     SQLITE3_COLUMN_BLOB(3)

NAME
     sqlite3_column_blob, sqlite3_column_bytes, sqlite3_column_bytes16,
     sqlite3_column_double, sqlite3_column_int, sqlite3_column_int64,
     sqlite3_column_text, sqlite3_column_text16, sqlite3_column_type,
     sqlite3_column_value - Result Values From A Query

SYNOPSIS
     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);

     sqlite3_int64
     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);

     sqlite3_value *
     sqlite3_column_value(sqlite3_stmt*, int iCol);

DESCRIPTION
     These routines return information about a single column of the current
     result row of a query.  In every case the first argument is a pointer to
     the prepared statement that is being evaluated (the sqlite3_stmt* that
     was returned from sqlite3_prepare_v2() or one of its variants) and the
     second argument is the index of the column for which information should
     be returned.  The leftmost column of the result set has the index 0.  The
     number of columns in the result can be determined using
     sqlite3_column_count().

     If the SQL statement does not currently point to a valid row, or if the
     column index is out of range, the result is undefined.  These routines
     may only be called when the most recent call to sqlite3_step() has
     returned SQLITE_ROW and neither sqlite3_reset() nor sqlite3_finalize()
     have been called subsequently.  If any of these routines are called after
     sqlite3_reset() or sqlite3_finalize() or after sqlite3_step() has
     returned something other than SQLITE_ROW, the results are undefined.  If
     sqlite3_step() or sqlite3_reset() or sqlite3_finalize() are called from a
     different thread while any of these routines are pending, then the
     results are undefined.

     The sqlite3_column_type() routine returns the  datatype code for 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.  If the result is NULL, then sqlite3_column_bytes() returns
     zero.

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

     The values returned by sqlite3_column_bytes() and
     sqlite3_column_bytes16() do not include the zero terminators at the end
     of the string.  For clarity: the values returned by
     sqlite3_column_bytes() and sqlite3_column_bytes16() are the number of
     bytes in the string, not the number of characters.

     Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
     even empty strings, are always zero-terminated.  The return value from
     sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.

     Warning:  The object returned by sqlite3_column_value() is an unprotected
     sqlite3_value object.  In a multithreaded environment, an unprotected
     sqlite3_value object may only be used safely with sqlite3_bind_value()
     and sqlite3_result_value().  If the unprotected sqlite3_value object
     returned by sqlite3_column_value() is used in any other way, including
     calls to routines like sqlite3_value_int(), sqlite3_value_text(), or
     sqlite3_value_bytes(), the behavior is not threadsafe.

     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 perform the
     conversion automatically.  The following table details the conversions
     that are applied:

     <table border="1"> <tr><th> Internal<br>Type <th> Requested<br>Type <th>
     Conversion

     <tr><td>  NULL    <td> INTEGER   <td> Result is 0 <tr><td>  NULL <td>
     FLOAT    <td> Result is 0.0 <tr><td>  NULL    <td>   TEXT <td> Result is
     a NULL pointer <tr><td>  NULL    <td>   BLOB    <td> Result is a NULL
     pointer <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to
     float <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the
     integer <tr><td> INTEGER  <td>   BLOB    <td> Same as INTEGER->TEXT
     <tr><td>  FLOAT   <td> INTEGER   <td> CAST to INTEGER <tr><td> FLOAT
     <td>   TEXT    <td> ASCII rendering of the float <tr><td> FLOAT   <td>
     BLOB    <td> CAST to BLOB <tr><td>  TEXT    <td> INTEGER   <td> CAST to
     INTEGER <tr><td>  TEXT    <td>  FLOAT <td> CAST to REAL <tr><td>  TEXT
     <td>   BLOB    <td> No change <tr><td>  BLOB    <td> INTEGER   <td> CAST
     to INTEGER <tr><td> BLOB    <td>  FLOAT    <td> CAST to REAL <tr><td>
     BLOB    <td> TEXT    <td> Add a zero terminator if needed </table>

     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:

        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.

        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.

        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.

     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 references will have been modified.  Other
     kinds of conversion are done in place when it is possible, but sometimes
     they are not possible and in those cases prior pointers are invalidated.

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

        sqlite3_column_text() followed by sqlite3_column_bytes()

        sqlite3_column_blob() followed by sqlite3_column_bytes()

        sqlite3_column_text16() followed by sqlite3_column_bytes16()

     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
     calls 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().

     The pointers returned are valid until a type conversion occurs as
     described above, or until sqlite3_step() or sqlite3_reset() or
     sqlite3_finalize() is called.  The memory space used to hold strings and
     BLOBs is freed automatically.  Do <em>not</em> pass the pointers returned
     from sqlite3_column_blob(), sqlite3_column_text(), etc.  into
     sqlite3_free().

     If a memory allocation error occurs during the evaluation of any of these
     routines, a default value is returned.  The default value is either the
     integer 0, the floating point number 0.0, or a NULL pointer.  Subsequent
     calls to sqlite3_errcode() will return SQLITE_NOMEM.

SEE ALSO
     sqlite3_stmt(3), sqlite3_bind_blob(3), sqlite3_column_blob(3),
     sqlite3_column_count(3), sqlite3_column_blob(3), sqlite3_errcode(3),
     sqlite3_finalize(3), sqlite3_malloc(3), sqlite3_prepare(3),
     sqlite3_reset(3), sqlite3_result_blob(3), sqlite3_mprintf(3),
     sqlite3_step(3), sqlite3_value_blob(3), SQLITE_INTEGER(3), SQLITE_OK(3),
     SQLITE_INTEGER(3), SQLITE_OK(3), SQLITE_INTEGER(3), sqlite3_value(3)

NetBSD 8.0                      March 11, 2017                      NetBSD 8.0