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
|
<!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>Function Auxiliary Data</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_get_auxdata sqlite3_set_auxdata -->
<div class=nosearch>
<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
<h2>Function Auxiliary Data</h2>
</div>
<blockquote><pre>
void *sqlite3_get_auxdata(sqlite3_context*, int N);
void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
</pre></blockquote>
<p>
These functions may be used by (non-aggregate) SQL functions to
associate auxiliary data with argument values. If the same argument
value is passed to multiple invocations of the same SQL function during
query execution, under some circumstances the associated auxiliary data
might be preserved. An example of where this might be useful is in a
regular-expression matching function. The compiled version of the regular
expression can be stored as auxiliary data associated with the pattern string.
Then as long as the pattern string remains the same,
the compiled regular expression can be reused on multiple
invocations of the same function.</p>
<p>The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary data
associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth argument
value to the application-defined function. N is zero for the left-most
function argument. If there is no auxiliary data
associated with the function argument, the sqlite3_get_auxdata(C,N) interface
returns a NULL pointer.</p>
<p>The sqlite3_set_auxdata(C,N,P,X) interface saves P as auxiliary data for the
N-th argument of the application-defined function. Subsequent
calls to sqlite3_get_auxdata(C,N) return P from the most recent
sqlite3_set_auxdata(C,N,P,X) call if the auxiliary data is still valid or
NULL if the auxiliary data has been discarded.
After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
SQLite will invoke the destructor function X with parameter P exactly
once, when the auxiliary data is discarded.
SQLite is free to discard the auxiliary data at any time, including: <ul>
<li> when the corresponding function parameter changes, or
<li> when <a href="../c3ref/reset.html">sqlite3_reset()</a> or <a href="../c3ref/finalize.html">sqlite3_finalize()</a> is called for the
SQL statement, or
<li> when sqlite3_set_auxdata() is invoked again on the same
parameter, or
<li> during the original sqlite3_set_auxdata() call when a memory
allocation error occurs.
<li> during the original sqlite3_set_auxdata() call if the function
is evaluated during query planning instead of during query execution,
as sometimes happens with <a href="../compile.html#enable_stat4">SQLITE_ENABLE_STAT4</a>. </ul></p>
<p>Note the last two bullets in particular. The destructor X in
sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata()
should be called near the end of the function implementation and the
function implementation should not make any use of P after
sqlite3_set_auxdata() has been called. Furthermore, a call to
sqlite3_get_auxdata() that occurs immediately after a corresponding call
to sqlite3_set_auxdata() might still return NULL if an out-of-memory
condition occurred during the sqlite3_set_auxdata() call or if the
function is being evaluated during query planning rather than during
query execution.</p>
<p>In practice, auxiliary data is preserved between function calls for
function parameters that are compile-time constants, including literal
values and <a href="../lang_expr.html#varparam">parameters</a> and expressions composed from the same.</p>
<p>The value of the N parameter to these interfaces should be non-negative.
Future enhancements may make use of negative N values to define new
kinds of function caching behavior.</p>
<p>These routines must be called from the same thread in which
the SQL function is running.</p>
<p>See also: <a href="../c3ref/get_clientdata.html">sqlite3_get_clientdata()</a> and <a href="../c3ref/get_clientdata.html">sqlite3_set_clientdata()</a>.
</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>
|
