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