1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Setting The Result Of An SQL Function</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(../images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(../images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(../images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
71
<a href="../index.html">
72
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="../about.html">About</a>
83
<a href="../sitemap.html">Sitemap</a>
84
<a href="../docs.html">Documentation</a>
85
<a href="../download.html">Download</a>
86
<a href="../copyright.html">License</a>
87
<a href="../news.html">News</a>
88
<a href="../support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
120
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Setting The Result Of An SQL Function</h2><blockquote><pre>void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
121
void sqlite3_result_double(sqlite3_context*, double);
122
void sqlite3_result_error(sqlite3_context*, const char*, int);
123
void sqlite3_result_error16(sqlite3_context*, const void*, int);
124
void sqlite3_result_error_toobig(sqlite3_context*);
125
void sqlite3_result_error_nomem(sqlite3_context*);
126
void sqlite3_result_error_code(sqlite3_context*, int);
127
void sqlite3_result_int(sqlite3_context*, int);
128
void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
129
void sqlite3_result_null(sqlite3_context*);
130
void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
131
void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
132
void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
133
void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
134
void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
135
void sqlite3_result_zeroblob(sqlite3_context*, int n);
136
</pre></blockquote><p>
137
These routines are used by the xFunc or xFinal callbacks that
138
implement SQL functions and aggregates. See
139
<a href="../c3ref/create_function.html">sqlite3_create_function()</a> and <a href="../c3ref/create_function.html">sqlite3_create_function16()</a>
140
for additional information.</p>
142
<p>These functions work very much like the <a href="../c3ref/bind_blob.html">parameter binding</a> family of
143
functions used to bind values to host parameters in prepared statements.
144
Refer to the <a href="../c3ref/bind_blob.html">SQL parameter</a> documentation for additional information.</p>
146
<p>The sqlite3_result_blob() interface sets the result from
147
an application-defined function to be the BLOB whose content is pointed
148
to by the second parameter and which is N bytes long where N is the
151
<p>The sqlite3_result_zeroblob() interfaces set the result of
152
the application-defined function to be a BLOB containing all zero
153
bytes and N bytes in size, where N is the value of the 2nd parameter.</p>
155
<p>The sqlite3_result_double() interface sets the result from
156
an application-defined function to be a floating point value specified
157
by its 2nd argument.</p>
159
<p>The sqlite3_result_error() and sqlite3_result_error16() functions
160
cause the implemented SQL function to throw an exception.
161
SQLite uses the string pointed to by the
162
2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
163
as the text of an error message. SQLite interprets the error
164
message string from sqlite3_result_error() as UTF-8. SQLite
165
interprets the string from sqlite3_result_error16() as UTF-16 in native
166
byte order. If the third parameter to sqlite3_result_error()
167
or sqlite3_result_error16() is negative then SQLite takes as the error
168
message all text up through the first zero character.
169
If the third parameter to sqlite3_result_error() or
170
sqlite3_result_error16() is non-negative then SQLite takes that many
171
bytes (not characters) from the 2nd parameter as the error message.
172
The sqlite3_result_error() and sqlite3_result_error16()
173
routines make a private copy of the error message text before
174
they return. Hence, the calling function can deallocate or
175
modify the text after they return without harm.
176
The sqlite3_result_error_code() function changes the error code
177
returned by SQLite as a result of an error in a function. By default,
178
the error code is SQLITE_ERROR. A subsequent call to sqlite3_result_error()
179
or sqlite3_result_error16() resets the error code to SQLITE_ERROR.</p>
181
<p>The sqlite3_result_toobig() interface causes SQLite to throw an error
182
indicating that a string or BLOB is too long to represent.</p>
184
<p>The sqlite3_result_nomem() interface causes SQLite to throw an error
185
indicating that a memory allocation failed.</p>
187
<p>The sqlite3_result_int() interface sets the return value
188
of the application-defined function to be the 32-bit signed integer
189
value given in the 2nd argument.
190
The sqlite3_result_int64() interface sets the return value
191
of the application-defined function to be the 64-bit signed integer
192
value given in the 2nd argument.</p>
194
<p>The sqlite3_result_null() interface sets the return value
195
of the application-defined function to be NULL.</p>
197
<p>The sqlite3_result_text(), sqlite3_result_text16(),
198
sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
199
set the return value of the application-defined function to be
200
a text string which is represented as UTF-8, UTF-16 native byte order,
201
UTF-16 little endian, or UTF-16 big endian, respectively.
202
SQLite takes the text result from the application from
203
the 2nd parameter of the sqlite3_result_text* interfaces.
204
If the 3rd parameter to the sqlite3_result_text* interfaces
205
is negative, then SQLite takes result text from the 2nd parameter
206
through the first zero character.
207
If the 3rd parameter to the sqlite3_result_text* interfaces
208
is non-negative, then as many bytes (not characters) of the text
209
pointed to by the 2nd parameter are taken as the application-defined
210
function result. If the 3rd parameter is non-negative, then it
211
must be the byte offset into the string where the NUL terminator would
212
appear if the string where NUL terminated. If any NUL characters occur
213
in the string at a byte offset that is less than the value of the 3rd
214
parameter, then the resulting string will contain embedded NULs and the
215
result of expressions operating on strings with embedded NULs is undefined.
216
If the 4th parameter to the sqlite3_result_text* interfaces
217
or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
218
function as the destructor on the text or BLOB result when it has
219
finished using that result.
220
If the 4th parameter to the sqlite3_result_text* interfaces or to
221
sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
222
assumes that the text or BLOB result is in constant space and does not
223
copy the content of the parameter nor call a destructor on the content
224
when it has finished using that result.
225
If the 4th parameter to the sqlite3_result_text* interfaces
226
or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
227
then SQLite makes a copy of the result into space obtained from
228
from <a href="../c3ref/free.html">sqlite3_malloc()</a> before it returns.</p>
230
<p>The sqlite3_result_value() interface sets the result of
231
the application-defined function to be a copy the
232
<a href="../c3ref/value.html">unprotected sqlite3_value</a> object specified by the 2nd parameter. The
233
sqlite3_result_value() interface makes a copy of the <a href="../c3ref/value.html">sqlite3_value</a>
234
so that the <a href="../c3ref/value.html">sqlite3_value</a> specified in the parameter may change or
235
be deallocated after sqlite3_result_value() returns without harm.
236
A <a href="../c3ref/value.html">protected sqlite3_value</a> object may always be used where an
237
<a href="../c3ref/value.html">unprotected sqlite3_value</a> object is required, so either
238
kind of <a href="../c3ref/value.html">sqlite3_value</a> object can be used with this interface.</p>
240
<p>If these routines are called from within the different thread
241
than the one containing the application-defined function that received
242
the <a href="../c3ref/context.html">sqlite3_context</a> pointer, the results are undefined.
243
</p><p>See also lists of
244
<a href="objlist.html">Objects</a>,
245
<a href="constlist.html">Constants</a>, and
246
<a href="funclist.html">Functions</a>.</p>
added
removed
c3ref/result_blob.html
