Updated: 2021/Apr/14


SQLITE3_VALUE_BLOB(3)      Library Functions Manual      SQLITE3_VALUE_BLOB(3)

NAME
     sqlite3_value_blob, sqlite3_value_double, sqlite3_value_int,
     sqlite3_value_int64, sqlite3_value_pointer, sqlite3_value_text,
     sqlite3_value_text16, sqlite3_value_text16le, sqlite3_value_text16be,
     sqlite3_value_bytes, sqlite3_value_bytes16, sqlite3_value_type,
     sqlite3_value_numeric_type, sqlite3_value_nochange - Obtaining SQL Values

SYNOPSIS
     const void *
     sqlite3_value_blob(sqlite3_value*);

     double
     sqlite3_value_double(sqlite3_value*);

     int
     sqlite3_value_int(sqlite3_value*);

     sqlite3_int64
     sqlite3_value_int64(sqlite3_value*);

     void *
     sqlite3_value_pointer(sqlite3_value*, const char*);

     const unsigned char *
     sqlite3_value_text(sqlite3_value*);

     const void *
     sqlite3_value_text16(sqlite3_value*);

     const void *
     sqlite3_value_text16le(sqlite3_value*);

     const void *
     sqlite3_value_text16be(sqlite3_value*);

     int
     sqlite3_value_bytes(sqlite3_value*);

     int
     sqlite3_value_bytes16(sqlite3_value*);

     int
     sqlite3_value_type(sqlite3_value*);

     int
     sqlite3_value_numeric_type(sqlite3_value*);

     int
     sqlite3_value_nochange(sqlite3_value*);

DESCRIPTION
     Summary:

     <table border=0 cellpadding=0 cellspacing=0>
     <tr><td>sqlite3_value_blob<td>&rarr;<td>BLOB value
     <tr><td>sqlite3_value_double<td>&rarr;<td>REAL value
     <tr><td>sqlite3_value_int<td>&rarr;<td>32-bit INTEGER value
     <tr><td>sqlite3_value_int64<td>&rarr;<td>64-bit INTEGER value
     <tr><td>sqlite3_value_pointer<td>&rarr;<td>Pointer value
     <tr><td>sqlite3_value_text<td>&rarr;<td>UTF-8 TEXT value
     <tr><td>sqlite3_value_text16<td>&rarr;<td>UTF-16 TEXT value in the native
     byteorder <tr><td>sqlite3_value_text16be<td>&rarr;<td>UTF-16be TEXT value
     <tr><td>sqlite3_value_text16le<td>&rarr;<td>UTF-16le TEXT value <tr><td>
     <td> <td>  <tr><td>sqlite3_value_bytes<td>&rarr;<td>Size of a BLOB or a
     UTF-8 TEXT in bytes <tr><td>sqlite3_value_bytes16   <td>&rarr;  <td>Size
     of UTF-16 TEXT in bytes <tr><td>sqlite3_value_type<td>&rarr;<td>Default
     datatype of the value <tr><td>sqlite3_value_numeric_type   <td>&rarr;
     <td>Best numeric datatype of the value <tr><td>sqlite3_value_nochange
     <td>&rarr;  <td>True if the column is unchanged in an UPDATE against a
     virtual table.  </table>

     Details:

     These routines extract type, size, and content information from protected
     sqlite3_value objects.  Protected sqlite3_value objects are used to pass
     parameter information into implementation of application-defined SQL
     functions and virtual tables.

     These routines work only with protected sqlite3_value objects.  Any
     attempt to use these routines on an unprotected sqlite3_value is not
     threadsafe.

     These routines work just like the corresponding column access functions
     except that these routines take a single protected sqlite3_value object
     pointer instead of a sqlite3_stmt* pointer and an integer column number.

     The sqlite3_value_text16() interface extracts a UTF-16 string in the
     native byte-order of the host machine.  The sqlite3_value_text16be() and
     sqlite3_value_text16le() interfaces extract UTF-16 strings as big-endian
     and little-endian respectively.

     If sqlite3_value object V was initialized using
     sqlite3_bind_pointer(S,I,P,X,D) or sqlite3_result_pointer(C,P,X,D) and if
     X and Y are strings that compare equal according to strcmp(X,Y), then
     sqlite3_value_pointer(V,Y) will return the pointer P.  Otherwise,
     sqlite3_value_pointer(V,Y) returns a NULL.  The sqlite3_bind_pointer()
     routine is part of the pointer passing interface added for SQLite 3.20.0.

     The sqlite3_value_type(V) interface returns the  datatype code for the
     initial datatype of the sqlite3_value object V.  The returned value is
     one of SQLITE_INTEGER, SQLITE_FLOAT, SQLITE_TEXT, SQLITE_BLOB, or
     SQLITE_NULL.  Other interfaces might change the datatype for an
     sqlite3_value object.  For example, if the datatype is initially
     SQLITE_INTEGER and sqlite3_value_text(V) is called to extract a text
     value for that integer, then subsequent calls to sqlite3_value_type(V)
     might return SQLITE_TEXT.  Whether or not a persistent internal datatype
     conversion occurs is undefined and may change from one release of SQLite
     to the next.

     The sqlite3_value_numeric_type() interface attempts to apply numeric
     affinity to the value.  This means that an attempt is made to convert the
     value to an integer or floating point.  If such a conversion is possible
     without loss of information (in other words, if the value is a string
     that looks like a number) then the conversion is performed.  Otherwise no
     conversion occurs.  The  datatype after conversion is returned.

     Within the xUpdate method of a virtual table, the
     sqlite3_value_nochange(X) interface returns true if and only if the
     column corresponding to X is unchanged by the UPDATE operation that the
     xUpdate method call was invoked to implement and if and the prior xColumn
     method call that was invoked to extracted the value for that column
     returned without setting a result (probably because it queried
     sqlite3_vtab_nochange() and found that the column was unchanging).
     Within an xUpdate method, any value for which sqlite3_value_nochange(X)
     is true will in all other respects appear to be a NULL value.  If
     sqlite3_value_nochange(X) is invoked anywhere other than within an
     xUpdate method call for an UPDATE statement, then the return value is
     arbitrary and meaningless.

     Please pay particular attention to the fact that the pointer returned
     from sqlite3_value_blob(), sqlite3_value_text(), or
     sqlite3_value_text16() can be invalidated by a subsequent call to
     sqlite3_value_bytes(), sqlite3_value_bytes16(), sqlite3_value_text(), or
     sqlite3_value_text16().

     These routines must be called from the same thread as the SQL function
     that supplied the sqlite3_value* parameters.

     As long as the input parameter is correct, these routines can only fail
     if an out-of-memory error occurs during a format conversion.  Only the
     following subset of interfaces are subject to out-of-memory errors:

        sqlite3_value_blob()

        sqlite3_value_text()

        sqlite3_value_text16()

        sqlite3_value_text16le()

        sqlite3_value_text16be()

        sqlite3_value_bytes()

        sqlite3_value_bytes16()

     If an out-of-memory error occurs, then the return value from these
     routines is the same as if the column had contained an SQL NULL value.
     Valid SQL NULL returns can be distinguished from out-of-memory errors by
     invoking the sqlite3_errcode() immediately after the suspect return value
     is obtained and before any other SQLite interface is called on the same
     database connection.

SEE ALSO
     sqlite3_create_function(3), sqlite3_column_blob(3), sqlite3(3),
     sqlite3_value(3), sqlite3_errcode(3), sqlite3_value(3),
     sqlite3_value_blob(3), sqlite3_vtab_nochange(3), SQLITE_INTEGER(3),
     sqlite3_value(3)

NetBSD 9.99                    December 19, 2018                   NetBSD 9.99