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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Setting The Result Of An SQL Function</title>
<style type="text/css">
body {
margin: auto;
font-family: Verdana, sans-serif;
padding: 8px 1%;
}
a { color: #044a64 }
a:visited { color: #734559 }
.logo { position:absolute; margin:3px; }
.tagline {
float:right;
text-align:right;
font-style:italic;
width:300px;
margin:12px;
margin-top:58px;
}
.menubar {
clear: both;
border-radius: 8px;
background: #044a64;
padding: 0px;
margin: 0px;
cell-spacing: 0px;
}
.toolbar {
text-align: center;
line-height: 1.6em;
margin: 0;
padding: 0px 8px;
}
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
.toolbar a:visited { color: white; }
.toolbar a:hover { color: #044a64; background: white; }
.content { margin: 5%; }
.content dt { font-weight:bold; }
.content dd { margin-bottom: 25px; margin-left:20%; }
.content ul { padding:0px; padding-left: 15px; margin:0px; }
/* Things for "fancyformat" documents start here. */
.fancy img+p {font-style:italic}
.fancy .codeblock i { color: darkblue; }
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
.fancy h2 { margin-left: 10px }
.fancy h3 { margin-left: 20px }
.fancy h4 { margin-left: 30px }
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
.fancy #toc a { color: darkblue ; text-decoration: none }
.fancy .todo { color: #AA3333 ; font-style : italic }
.fancy .todo:before { content: 'TODO:' }
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
.fancy img { display:block; }
.fancy :link:hover, .fancy :visited:hover { background: wheat }
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
.fancy li p { margin: 1em 0 }
/* End of "fancyformat" specific rules. */
</style>
</head>
<body>
<div><!-- container div to satisfy validator -->
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
<table width=100% class="menubar"><tr>
<td width=100%>
<div class="toolbar">
<a href="../about.html">About</a>
<a href="../sitemap.html">Sitemap</a>
<a href="../docs.html">Documentation</a>
<a href="../download.html">Download</a>
<a href="../copyright.html">License</a>
<a href="../news.html">News</a>
<a href="../support.html">Support</a>
</div>
<script>
gMsg = "Search SQLite Docs..."
function entersearch() {
var q = document.getElementById("q");
if( q.value == gMsg ) { q.value = "" }
q.style.color = "black"
q.style.fontStyle = "normal"
}
function leavesearch() {
var q = document.getElementById("q");
if( q.value == "" ) {
q.value = gMsg
q.style.color = "#044a64"
q.style.fontStyle = "italic"
}
}
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;
}
</script>
<td>
<div style="padding:0 1em 0px 0;white-space:nowrap">
<form name=f method="GET" action="http://www.sqlite.org/search">
<input id=q name=q type=text
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...">
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
</form>
</div>
</table>
<div class=startsearch></div>
<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*));
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_zeroblob(sqlite3_context*, int 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() 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.</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 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.</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 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 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
from <a href="../c3ref/free.html">sqlite3_malloc()</a> before it returns.</p>
<p>The sqlite3_result_value() interface sets the result of
the application-defined function to be a copy 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>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="objlist.html">Objects</a>,
<a href="constlist.html">Constants</a>, and
<a href="funclist.html">Functions</a>.</p>
|
