Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## 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 sqlite3_bind_* family of functions used to bind values to host parameters in prepared statements. Refer to the sqlite3_bind_* 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() inerfaces 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 UTF8. SQLite interprets the string from sqlite3_result_error16() as UTF16 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 copy 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 exception indicating that the 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 constant space and does not copy the space 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 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 recieved the sqlite3_context pointer, the results are undefined.

### Invariants:

F16403 | The default return value from any SQL function is NULL.
F16406 | 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.
F16409 | The sqlite3_result_double(C,V) interface changes the return value of function C to be the floating point value V.
F16412 | 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 UTF8 error message copied from V up to the first zero byte or until N bytes are read if N is positive.
F16415 | 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 UTF16 native byte order error message copied from V up to the first zero terminator or until N bytes are read if N is positive.
F16418 | 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.
F16421 | 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.
F16424 | 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.
F16427 | The sqlite3_result_int(C,V) interface changes the return value of function C to be the 32-bit integer value V.
F16430 | The sqlite3_result_int64(C,V) interface changes the return value of function C to be the 64-bit integer value V.
F16433 | The sqlite3_result_null(C) interface changes the return value of function C to be NULL.
F16436 | The sqlite3_result_text(C,V,N,D) interface changes the return value of function C to be the UTF8 string V up to the first zero if N is negative or the first N bytes of V if N is non-negative.
F16439 | The sqlite3_result_text16(C,V,N,D) interface changes the return value of function C to be the UTF16 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.
F16442 | The sqlite3_result_text16be(C,V,N,D) interface changes the return value of function C to be the UTF16 big-endian string V up to the first zero if N is is negative or the first N bytes or V if N is non-negative.
F16445 | The sqlite3_result_text16le(C,V,N,D) interface changes the return value of function C to be the UTF16 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.
F16448 | The sqlite3_result_value(C,V) interface changes the return value of function C to be unprotected sqlite3_value object V.
F16451 | The sqlite3_result_zeroblob(C,N) interface changes the return value of function C to be an N-byte blob of all zeros.
F16454 | The sqlite3_result_error() and sqlite3_result_error16() interfaces make a copy of their error message strings before returning.
F16457 | 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.
F16460 | 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.
F16463 | 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/05/12 13:08:44 UTC