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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<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>
</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_div("searchmenu")'>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">
<span class="desktoponly">Search for:</span> <input type="text" name="q">
<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 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.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;
}
</script>
</div>
<!-- keywords: sqlite3_get_auxdata sqlite3_set_auxdata -->
<div class=nosearch>
<a href="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 metadata with argument values. If the same value is passed to
multiple invocations of the same SQL function during query execution, under
some circumstances the associated metadata may 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
metadata 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() interface returns a pointer to the metadata
associated by the sqlite3_set_auxdata() function with the Nth argument
value to the application-defined function. If there is no metadata
associated with the function argument, this sqlite3_get_auxdata() interface
returns a NULL pointer.</p>
<p>The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata 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 metadata is still valid or
NULL if the metadata 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 metadata is discarded.
SQLite is free to discard the metadata 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. </ul></p>
<p>Note the last bullet 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.</p>
<p>In practice, metadata 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>These routines must be called from the same thread in which
the SQL function is running.
</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>
|
