1.Dd December 19, 2018 2.Dt SQLITE3_VALUE_BLOB 3 3.Os 4.Sh NAME 5.Nm sqlite3_value_blob , 6.Nm sqlite3_value_double , 7.Nm sqlite3_value_int , 8.Nm sqlite3_value_int64 , 9.Nm sqlite3_value_pointer , 10.Nm sqlite3_value_text , 11.Nm sqlite3_value_text16 , 12.Nm sqlite3_value_text16le , 13.Nm sqlite3_value_text16be , 14.Nm sqlite3_value_bytes , 15.Nm sqlite3_value_bytes16 , 16.Nm sqlite3_value_type , 17.Nm sqlite3_value_numeric_type , 18.Nm sqlite3_value_nochange 19.Nd Obtaining SQL Values 20.Sh SYNOPSIS 21.Ft const void * 22.Fo sqlite3_value_blob 23.Fa "sqlite3_value*" 24.Fc 25.Ft double 26.Fo sqlite3_value_double 27.Fa "sqlite3_value*" 28.Fc 29.Ft int 30.Fo sqlite3_value_int 31.Fa "sqlite3_value*" 32.Fc 33.Ft sqlite3_int64 34.Fo sqlite3_value_int64 35.Fa "sqlite3_value*" 36.Fc 37.Ft void * 38.Fo sqlite3_value_pointer 39.Fa "sqlite3_value*" 40.Fa "const char*" 41.Fc 42.Ft const unsigned char * 43.Fo sqlite3_value_text 44.Fa "sqlite3_value*" 45.Fc 46.Ft const void * 47.Fo sqlite3_value_text16 48.Fa "sqlite3_value*" 49.Fc 50.Ft const void * 51.Fo sqlite3_value_text16le 52.Fa "sqlite3_value*" 53.Fc 54.Ft const void * 55.Fo sqlite3_value_text16be 56.Fa "sqlite3_value*" 57.Fc 58.Ft int 59.Fo sqlite3_value_bytes 60.Fa "sqlite3_value*" 61.Fc 62.Ft int 63.Fo sqlite3_value_bytes16 64.Fa "sqlite3_value*" 65.Fc 66.Ft int 67.Fo sqlite3_value_type 68.Fa "sqlite3_value*" 69.Fc 70.Ft int 71.Fo sqlite3_value_numeric_type 72.Fa "sqlite3_value*" 73.Fc 74.Ft int 75.Fo sqlite3_value_nochange 76.Fa "sqlite3_value*" 77.Fc 78.Sh DESCRIPTION 79\fBSummary:\fP 80.Bd -ragged 81<table border=0 cellpadding=0 cellspacing=0> <tr><td>\fBsqlite3_value_blob\fP<td>→<td>BLOB 82value <tr><td>\fBsqlite3_value_double\fP<td>→<td>REAL value <tr><td>\fBsqlite3_value_int\fP<td>→<td>32-bit 83INTEGER value <tr><td>\fBsqlite3_value_int64\fP<td>→<td>64-bit INTEGER 84value <tr><td>\fBsqlite3_value_pointer\fP<td>→<td>Pointer value <tr><td>\fBsqlite3_value_text\fP<td>→<td>UTF-8 85TEXT value <tr><td>\fBsqlite3_value_text16\fP<td>→<td>UTF-16 TEXT value 86in the native byteorder <tr><td>\fBsqlite3_value_text16be\fP<td>→<td>UTF-16be 87TEXT value <tr><td>\fBsqlite3_value_text16le\fP<td>→<td>UTF-16le TEXT 88value <tr><td> <td> <td> <tr><td>\fBsqlite3_value_bytes\fP<td>→<td>Size 89of a BLOB or a UTF-8 TEXT in bytes <tr><td>\fBsqlite3_value_bytes16 \fP 90<td>→ <td>Size of UTF-16 TEXT in bytes <tr><td>\fBsqlite3_value_type\fP<td>→<td>Default 91datatype of the value <tr><td>\fBsqlite3_value_numeric_type \fP <td>→ <td>Best 92numeric datatype of the value <tr><td>\fBsqlite3_value_nochange \fP <td>→ <td>True 93if the column is unchanged in an UPDATE against a virtual table. 94</table> 95.Ed 96.Pp 97\fBDetails:\fP 98.Pp 99These routines extract type, size, and content information from protected sqlite3_value 100objects. 101Protected sqlite3_value objects are used to pass parameter information 102into implementation of application-defined SQL functions 103and virtual tables. 104.Pp 105These routines work only with protected sqlite3_value 106objects. 107Any attempt to use these routines on an unprotected sqlite3_value 108is not threadsafe. 109.Pp 110These routines work just like the corresponding column access functions 111except that these routines take a single protected sqlite3_value 112object pointer instead of a sqlite3_stmt* pointer and 113an integer column number. 114.Pp 115The sqlite3_value_text16() interface extracts a UTF-16 string in the 116native byte-order of the host machine. 117The sqlite3_value_text16be() and sqlite3_value_text16le() interfaces 118extract UTF-16 strings as big-endian and little-endian respectively. 119.Pp 120If sqlite3_value object V was initialized using sqlite3_bind_pointer(S,I,P,X,D) 121or sqlite3_result_pointer(C,P,X,D) and 122if X and Y are strings that compare equal according to strcmp(X,Y), 123then sqlite3_value_pointer(V,Y) will return the pointer P. 124Otherwise, sqlite3_value_pointer(V,Y) returns a NULL. 125The sqlite3_bind_pointer() routine is part of the pointer passing interface 126added for SQLite 3.20.0. 127.Pp 128The sqlite3_value_type(V) interface returns the datatype code 129for the initial datatype of the sqlite3_value object V. 130The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT, 131SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL. 132Other interfaces might change the datatype for an sqlite3_value object. 133For example, if the datatype is initially SQLITE_INTEGER and sqlite3_value_text(V) 134is called to extract a text value for that integer, then subsequent 135calls to sqlite3_value_type(V) might return SQLITE_TEXT. 136Whether or not a persistent internal datatype conversion occurs is 137undefined and may change from one release of SQLite to the next. 138.Pp 139The sqlite3_value_numeric_type() interface attempts to apply numeric 140affinity to the value. 141This means that an attempt is made to convert the value to an integer 142or floating point. 143If such a conversion is possible without loss of information (in other 144words, if the value is a string that looks like a number) then the 145conversion is performed. 146Otherwise no conversion occurs. 147The datatype after conversion is returned. 148.Pp 149Within the xUpdate method of a virtual table, the 150sqlite3_value_nochange(X) interface returns true if and only if the 151column corresponding to X is unchanged by the UPDATE operation that 152the xUpdate method call was invoked to implement and if and the prior 153xColumn method call that was invoked to extracted the value 154for that column returned without setting a result (probably because 155it queried sqlite3_vtab_nochange() and found 156that the column was unchanging). 157Within an xUpdate method, any value for which sqlite3_value_nochange(X) 158is true will in all other respects appear to be a NULL value. 159If sqlite3_value_nochange(X) is invoked anywhere other than within 160an xUpdate method call for an UPDATE statement, then the return 161value is arbitrary and meaningless. 162.Pp 163Please pay particular attention to the fact that the pointer returned 164from sqlite3_value_blob(), sqlite3_value_text(), 165or sqlite3_value_text16() can be invalidated 166by a subsequent call to sqlite3_value_bytes(), 167sqlite3_value_bytes16(), sqlite3_value_text(), 168or sqlite3_value_text16(). 169.Pp 170These routines must be called from the same thread as the SQL function 171that supplied the sqlite3_value* parameters. 172.Pp 173As long as the input parameter is correct, these routines can only 174fail if an out-of-memory error occurs during a format conversion. 175Only the following subset of interfaces are subject to out-of-memory 176errors: 177.Bl -bullet 178.It 179sqlite3_value_blob() 180.It 181sqlite3_value_text() 182.It 183sqlite3_value_text16() 184.It 185sqlite3_value_text16le() 186.It 187sqlite3_value_text16be() 188.It 189sqlite3_value_bytes() 190.It 191sqlite3_value_bytes16() 192.El 193.Pp 194If an out-of-memory error occurs, then the return value from these 195routines is the same as if the column had contained an SQL NULL value. 196Valid SQL NULL returns can be distinguished from out-of-memory errors 197by invoking the sqlite3_errcode() immediately after 198the suspect return value is obtained and before any other SQLite interface 199is called on the same database connection. 200.Sh SEE ALSO 201.Xr sqlite3_create_function 3 , 202.Xr sqlite3_column_blob 3 , 203.Xr sqlite3 3 , 204.Xr sqlite3_value 3 , 205.Xr sqlite3_errcode 3 , 206.Xr sqlite3_value 3 , 207.Xr sqlite3_value_blob 3 , 208.Xr sqlite3_vtab_nochange 3 , 209.Xr SQLITE_INTEGER 3 , 210.Xr sqlite3_value 3 211