160 lines
6.2 KiB
HTML
160 lines
6.2 KiB
HTML
<!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;
|
|
}
|
|
</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(C,N) interface returns a pointer to the metadata
|
|
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 metadata
|
|
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 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>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 lists of
|
|
<a href="objlist.html">Objects</a>,
|
|
<a href="constlist.html">Constants</a>, and
|
|
<a href="funclist.html">Functions</a>.</p>
|