Debian Codegraph @

www/c3ref/get_auxdata.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>Function Auxiliary Data</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <!-- keywords: sqlite3_get_auxdata sqlite3_set_auxdata -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Function Auxiliary Data</h2>
122 </div>
123 <blockquote><pre>
124 void *sqlite3_get_auxdata(sqlite3_context*, int N);
125 void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
126 </pre></blockquote>
127 <p>
128 These functions may be used by (non-aggregate) SQL functions to
129 associate auxiliary data with argument values. If the same argument
130 value is passed to multiple invocations of the same SQL function during
131 query execution, under some circumstances the associated auxiliary data
132 might be preserved. An example of where this might be useful is in a
133 regular-expression matching function. The compiled version of the regular
134 expression can be stored as auxiliary data associated with the pattern
135 string. Then as long as the pattern string remains the same,
136 the compiled regular expression can be reused on multiple
137 invocations of the same function.</p>
138
139 <p>The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary
140 data associated by the sqlite3_set_auxdata(C,N,P,X) function with the
141 Nth argument value to the application-defined function. N is zero
142 for the left-most function argument. If there is no auxiliary data
143 associated with the function argument, the sqlite3_get_auxdata(C,N)
144 interface returns a NULL pointer.</p>
145
146 <p>The sqlite3_set_auxdata(C,N,P,X) interface saves P as auxiliary data for the
147 N-th argument of the application-defined function. Subsequent
148 calls to sqlite3_get_auxdata(C,N) return P from the most recent
149 sqlite3_set_auxdata(C,N,P,X) call if the auxiliary data is still valid or
150 NULL if the auxiliary data has been discarded.
151 After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL,
152 SQLite will invoke the destructor function X with parameter P exactly
153 once, when the auxiliary data is discarded.
154 SQLite is free to discard the auxiliary data at any time, including: <ul>
155 <li> when the corresponding function parameter changes, or
156 <li> when <a href="../c3ref/reset.html">sqlite3_reset()</a> or <a href="../c3ref/finalize.html">sqlite3_finalize()</a> is called for the
157 SQL statement, or
158 <li> when sqlite3_set_auxdata() is invoked again on the same
159 parameter, or
160 <li> during the original sqlite3_set_auxdata() call when a memory
161 allocation error occurs.
162 <li> during the original sqlite3_set_auxdata() call if the function
163 is evaluated during query planning instead of during query execution,
164 as sometimes happens with <a href="../compile.html#enable_stat4">SQLITE_ENABLE_STAT4</a>. </ul></p>
165
166 <p>Note the last two bullets in particular. The destructor X in
167 sqlite3_set_auxdata(C,N,P,X) might be called immediately, before the
168 sqlite3_set_auxdata() interface even returns. Hence sqlite3_set_auxdata()
169 should be called near the end of the function implementation and the
170 function implementation should not make any use of P after
171 sqlite3_set_auxdata() has been called. Furthermore, a call to
172 sqlite3_get_auxdata() that occurs immediately after a corresponding call
173 to sqlite3_set_auxdata() might still return NULL if an out-of-memory
174 condition occurred during the sqlite3_set_auxdata() call or if the
175 function is being evaluated during query planning rather than during
176 query execution.</p>
177
178 <p>In practice, auxiliary data is preserved between function calls for
179 function parameters that are compile-time constants, including literal
180 values and <a href="../lang_expr.html#varparam">parameters</a> and expressions composed from the same.</p>
181
182 <p>The value of the N parameter to these interfaces should be non-negative.
183 Future enhancements may make use of negative N values to define new
184 kinds of function caching behavior.</p>
185
186 <p>These routines must be called from the same thread in which
187 the SQL function is running.</p>
188
189 <p>See also: <a href="../c3ref/get_clientdata.html">sqlite3_get_clientdata()</a> and <a href="../c3ref/get_clientdata.html">sqlite3_set_clientdata()</a>.
190 </p><p>See also lists of
191 <a href="../c3ref/objlist.html">Objects</a>,
192 <a href="../c3ref/constlist.html">Constants</a>, and
193 <a href="../c3ref/funclist.html">Functions</a>.</p>
194