1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="../sqlite.css" rel="stylesheet">
<title>Setting The Result Of An SQL Function</title>
<!-- path=../ -->
</head>
<body>
<div class=nosearch>
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="../index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='../about.html'>About</a>
<li class='desktoponly'><a href="../docs.html">Documentation</a>
<li class='desktoponly'><a href="../download.html">Download</a>
<li class='wideonly'><a href='../copyright.html'>License</a>
<li class='desktoponly'><a href="../support.html">Support</a>
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='../about.html'>About</a>
<li><a href='../docs.html'>Documentation</a>
<li><a href='../download.html'>Download</a>
<li><a href='../support.html'>Support</a>
<li><a href='../prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="../search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<!-- keywords: sqlite3_result_blob sqlite3_result_blob64 sqlite3_result_double sqlite3_result_error sqlite3_result_error16 sqlite3_result_error_code sqlite3_result_error_nomem sqlite3_result_error_toobig sqlite3_result_int sqlite3_result_int64 sqlite3_result_null sqlite3_result_pointer sqlite3_result_text sqlite3_result_text16 sqlite3_result_text16be sqlite3_result_text16le sqlite3_result_text64 sqlite3_result_value sqlite3_result_zeroblob sqlite3_result_zeroblob64 -->
<div class=nosearch>
<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
<h2>Setting The Result Of An SQL Function</h2>
</div>
<blockquote><pre>
void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
void sqlite3_result_blob64(sqlite3_context*,const void*,
sqlite3_uint64,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_text64(sqlite3_context*, const char*,sqlite3_uint64,
void(*)(void*), unsigned char encoding);
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_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
void sqlite3_result_zeroblob(sqlite3_context*, int n);
int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
</pre></blockquote>
<p>
These routines are used by the xFunc or xFinal callbacks that
implement SQL functions and aggregates. See
<a href="../c3ref/create_function.html">sqlite3_create_function()</a> and <a href="../c3ref/create_function.html">sqlite3_create_function16()</a>
for additional information.</p>
<p>These functions work very much like the <a href="../c3ref/bind_blob.html">parameter binding</a> family of
functions used to bind values to host parameters in prepared statements.
Refer to the <a href="../c3ref/bind_blob.html">SQL parameter</a> documentation for additional information.</p>
<p>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.</p>
<p>The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
interfaces set the result of the application-defined function to be
a BLOB containing all zero bytes and N bytes in size.</p>
<p>The sqlite3_result_double() interface sets the result from
an application-defined function to be a floating point value specified
by its 2nd argument.</p>
<p>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 using
the same <a href="../c3ref/bind_blob.html#byteorderdeterminationrules">byte-order determination rules</a> as <a href="../c3ref/bind_blob.html">sqlite3_bind_text16()</a>.
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.</p>
<p>The sqlite3_result_error_toobig() interface causes SQLite to throw an
error indicating that a string or BLOB is too long to represent.</p>
<p>The sqlite3_result_error_nomem() interface causes SQLite to throw an
error indicating that a memory allocation failed.</p>
<p>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.</p>
<p>The sqlite3_result_null() interface sets the return value
of the application-defined function to be NULL.</p>
<p>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.
The sqlite3_result_text64() interface sets the return value of an
application-defined function to be a text string in an encoding
specified by the fifth (and last) parameter, which must be one
of <a href="../c3ref/c_any.html">SQLITE_UTF8</a>, <a href="../c3ref/c_any.html">SQLITE_UTF16</a>, <a href="../c3ref/c_any.html">SQLITE_UTF16BE</a>, or <a href="../c3ref/c_any.html">SQLITE_UTF16LE</a>.
SQLite takes the text result from the application from
the 2nd parameter of the sqlite3_result_text* interfaces.
If the 3rd parameter to any of the sqlite3_result_text* interfaces
other than sqlite3_result_text64() is negative, then SQLite computes
the string length itself by searching the 2nd parameter for 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 3rd parameter is non-negative, then it
must be the byte offset into the string where the NUL terminator would
appear if the string where NUL terminated. If any NUL characters occur
in the string at a byte offset that is less than the value of the 3rd
parameter, then the resulting string will contain embedded NULs and the
result of expressions operating on strings with embedded NULs is undefined.
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 to
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 content of the parameter nor call a destructor on the content
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 <a href="../c3ref/free.html">sqlite3_malloc()</a> before it returns.</p>
<p>For the sqlite3_result_text16(), sqlite3_result_text16le(), and
sqlite3_result_text16be() routines, and for sqlite3_result_text64()
when the encoding is not UTF8, if the input UTF16 begins with a
byte-order mark (BOM, U+FEFF) then the BOM is removed from the
string and the rest of the string is interpreted according to the
byte-order specified by the BOM. The byte-order specified by
the BOM at the beginning of the text overrides the byte-order
specified by the interface procedure. So, for example, if
sqlite3_result_text16le() is invoked with text that begins
with bytes 0xfe, 0xff (a big-endian byte-order mark) then the
first two bytes of input are skipped and the remaining input
is interpreted as UTF16BE text.</p>
<p>For UTF16 input text to the sqlite3_result_text16(),
sqlite3_result_text16be(), sqlite3_result_text16le(), and
sqlite3_result_text64() routines, if the text contains invalid
UTF16 characters, the invalid characters might be converted
into the unicode replacement character, U+FFFD.</p>
<p>The sqlite3_result_value() interface sets the result of
the application-defined function to be a copy of the
<a href="../c3ref/value.html">unprotected sqlite3_value</a> object specified by the 2nd parameter. The
sqlite3_result_value() interface makes a copy of the <a href="../c3ref/value.html">sqlite3_value</a>
so that the <a href="../c3ref/value.html">sqlite3_value</a> specified in the parameter may change or
be deallocated after sqlite3_result_value() returns without harm.
A <a href="../c3ref/value.html">protected sqlite3_value</a> object may always be used where an
<a href="../c3ref/value.html">unprotected sqlite3_value</a> object is required, so either
kind of <a href="../c3ref/value.html">sqlite3_value</a> object can be used with this interface.</p>
<p>The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
SQL NULL value, just like <a href="../c3ref/result_blob.html">sqlite3_result_null(C)</a>, except that it
also associates the host-language pointer P or type T with that
NULL value such that the pointer can be retrieved within an
<a href="../appfunc.html">application-defined SQL function</a> using <a href="../c3ref/value_blob.html">sqlite3_value_pointer()</a>.
If the D parameter is not NULL, then it is a pointer to a destructor
for the P parameter. SQLite invokes D with P as its only argument
when SQLite is finished with P. The T parameter should be a static
string and preferably a string literal. The sqlite3_result_pointer()
routine is part of the <a href="../bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p>
<p>If these routines are called from within the different thread
than the one containing the application-defined function that received
the <a href="../c3ref/context.html">sqlite3_context</a> pointer, the results are undefined.
</p><p>See also lists of
<a href="../c3ref/objlist.html">Objects</a>,
<a href="../c3ref/constlist.html">Constants</a>, and
<a href="../c3ref/funclist.html">Functions</a>.</p>
|
