Small. Fast. Reliable.
Choose any three.

SQLite C Interface

Setting The Result Of An SQL Function

void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_double(sqlite3_context*, double);
void sqlite3_result_error(sqlite3_context*, const char*, int);
void sqlite3_result_error16(sqlite3_context*, const void*, int);
void sqlite3_result_error_toobig(sqlite3_context*);
void sqlite3_result_error_nomem(sqlite3_context*);
void sqlite3_result_error_code(sqlite3_context*, int);
void sqlite3_result_int(sqlite3_context*, int);
void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
void sqlite3_result_null(sqlite3_context*);
void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
void sqlite3_result_zeroblob(sqlite3_context*, int n);

These routines are used by the xFunc or xFinal callbacks that implement SQL functions and aggregates. See sqlite3_create_function() and sqlite3_create_function16() for additional information.

These functions work very much like the parameter binding family of functions used to bind values to host parameters in prepared statements. Refer to the SQL parameter documentation for additional information.

The sqlite3_result_blob() interface sets the result from an application-defined function to be the BLOB whose content is pointed to by the second parameter and which is N bytes long where N is the third parameter.

The sqlite3_result_zeroblob() interfaces set the result of the application-defined function to be a BLOB containing all zero bytes and N bytes in size, where N is the value of the 2nd parameter.

The sqlite3_result_double() interface sets the result from an application-defined function to be a floating point value specified by its 2nd argument.

The sqlite3_result_error() and sqlite3_result_error16() functions cause the implemented SQL function to throw an exception. SQLite uses the string pointed to by the 2nd parameter of sqlite3_result_error() or sqlite3_result_error16() as the text of an error message. SQLite interprets the error message string from sqlite3_result_error() as UTF-8. SQLite interprets the string from sqlite3_result_error16() as UTF-16 in native byte order. If the third parameter to sqlite3_result_error() or sqlite3_result_error16() is negative then SQLite takes as the error message all text up through the first zero character. If the third parameter to sqlite3_result_error() or sqlite3_result_error16() is non-negative then SQLite takes that many bytes (not characters) from the 2nd parameter as the error message. The sqlite3_result_error() and sqlite3_result_error16() routines make a private copy of the error message text before they return. Hence, the calling function can deallocate or modify the text after they return without harm. The sqlite3_result_error_code() function changes the error code returned by SQLite as a result of an error in a function. By default, the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error() or sqlite3_result_error16() resets the error code to SQLITE_ERROR.

The sqlite3_result_toobig() interface causes SQLite to throw an error indicating that a string or BLOB is to long to represent.

The sqlite3_result_nomem() interface causes SQLite to throw an error indicating that a memory allocation failed.

The sqlite3_result_int() interface sets the return value of the application-defined function to be the 32-bit signed integer value given in the 2nd argument. The sqlite3_result_int64() interface sets the return value of the application-defined function to be the 64-bit signed integer value given in the 2nd argument.

The sqlite3_result_null() interface sets the return value of the application-defined function to be NULL.

The sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces set the return value of the application-defined function to be a text string which is represented as UTF-8, UTF-16 native byte order, UTF-16 little endian, or UTF-16 big endian, respectively. SQLite takes the text result from the application from the 2nd parameter of the sqlite3_result_text* interfaces. If the 3rd parameter to the sqlite3_result_text* interfaces is negative, then SQLite takes result text from the 2nd parameter through the first zero character. If the 3rd parameter to the sqlite3_result_text* interfaces is non-negative, then as many bytes (not characters) of the text pointed to by the 2nd parameter are taken as the application-defined function result. If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that function as the destructor on the text or BLOB result when it has finished using that result. If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite assumes that the text or BLOB result is in constant space and does not copy the it or call a destructor when it has finished using that result. If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob is the special constant SQLITE_TRANSIENT then SQLite makes a copy of the result into space obtained from from sqlite3_malloc() before it returns.

The sqlite3_result_value() interface sets the result of the application-defined function to be a copy the unprotected sqlite3_value object specified by the 2nd parameter. The sqlite3_result_value() interface makes a copy of the sqlite3_value so that the sqlite3_value specified in the parameter may change or be deallocated after sqlite3_result_value() returns without harm. A protected sqlite3_value object may always be used where an unprotected sqlite3_value object is required, so either kind of sqlite3_value object can be used with this interface.

If these routines are called from within the different thread than the one containing the application-defined function that received the sqlite3_context pointer, the results are undefined.

Invariants:

H16403 The default return value from any SQL function is NULL.
H16406 The sqlite3_result_blob(C,V,N,D) interface changes the return value of function C to be a BLOB that is N bytes in length and with content pointed to by V.
H16409 The sqlite3_result_double(C,V) interface changes the return value of function C to be the floating point value V.
H16412 The sqlite3_result_error(C,V,N) interface changes the return value of function C to be an exception with error code SQLITE_ERROR and a UTF-8 error message copied from V up to the first zero byte or until N bytes are read if N is positive.
H16415 The sqlite3_result_error16(C,V,N) interface changes the return value of function C to be an exception with error code SQLITE_ERROR and a UTF-16 native byte order error message copied from V up to the first zero terminator or until N bytes are read if N is positive.
H16418 The sqlite3_result_error_toobig(C) interface changes the return value of the function C to be an exception with error code SQLITE_TOOBIG and an appropriate error message.
H16421 The sqlite3_result_error_nomem(C) interface changes the return value of the function C to be an exception with error code SQLITE_NOMEM and an appropriate error message.
H16424 The sqlite3_result_error_code(C,E) interface changes the return value of the function C to be an exception with error code E. The error message text is unchanged.
H16427 The sqlite3_result_int(C,V) interface changes the return value of function C to be the 32-bit integer value V.
H16430 The sqlite3_result_int64(C,V) interface changes the return value of function C to be the 64-bit integer value V.
H16433 The sqlite3_result_null(C) interface changes the return value of function C to be NULL.
H16436 The sqlite3_result_text(C,V,N,D) interface changes the return value of function C to be the UTF-8 string V up to the first zero if N is negative or the first N bytes of V if N is non-negative.
H16439 The sqlite3_result_text16(C,V,N,D) interface changes the return value of function C to be the UTF-16 native byte order string V up to the first zero if N is negative or the first N bytes of V if N is non-negative.
H16442 The sqlite3_result_text16be(C,V,N,D) interface changes the return value of function C to be the UTF-16 big-endian string V up to the first zero if N is negative or the first N bytes or V if N is non-negative.
H16445 The sqlite3_result_text16le(C,V,N,D) interface changes the return value of function C to be the UTF-16 little-endian string V up to the first zero if N is negative or the first N bytes of V if N is non-negative.
H16448 The sqlite3_result_value(C,V) interface changes the return value of function C to be the unprotected sqlite3_value object V.
H16451 The sqlite3_result_zeroblob(C,N) interface changes the return value of function C to be an N-byte BLOB of all zeros.
H16454 The sqlite3_result_error() and sqlite3_result_error16() interfaces make a copy of their error message strings before returning.
H16457 If the D destructor parameter to sqlite3_result_blob(C,V,N,D), sqlite3_result_text(C,V,N,D), sqlite3_result_text16(C,V,N,D), sqlite3_result_text16be(C,V,N,D), or sqlite3_result_text16le(C,V,N,D) is the constant SQLITE_STATIC then no destructor is ever called on the pointer V and SQLite assumes that V is immutable.
H16460 If the D destructor parameter to sqlite3_result_blob(C,V,N,D), sqlite3_result_text(C,V,N,D), sqlite3_result_text16(C,V,N,D), sqlite3_result_text16be(C,V,N,D), or sqlite3_result_text16le(C,V,N,D) is the constant SQLITE_TRANSIENT then the interfaces makes a copy of the content of V and retains the copy.
H16463 If the D destructor parameter to sqlite3_result_blob(C,V,N,D), sqlite3_result_text(C,V,N,D), sqlite3_result_text16(C,V,N,D), sqlite3_result_text16be(C,V,N,D), or sqlite3_result_text16le(C,V,N,D) is some value other than the constants SQLITE_STATIC and SQLITE_TRANSIENT then SQLite will invoke the destructor D with V as its only argument when it has finished with the V value.

See also lists of Objects, Constants, and Functions.


This page last modified 2008/12/09 18:44:04 UTC