268 lines
12 KiB
HTML
268 lines
12 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>Create Or Redefine SQL Functions</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: {function creation routines} sqlite3_create_function sqlite3_create_function16 sqlite3_create_function_v2 sqlite3_create_window_function -->
|
|
<div class=nosearch>
|
|
<a href="intro.html"><h2>SQLite C Interface</h2></a>
|
|
<h2>Create Or Redefine SQL Functions</h2>
|
|
</div>
|
|
<blockquote><pre>
|
|
int sqlite3_create_function(
|
|
sqlite3 *db,
|
|
const char *zFunctionName,
|
|
int nArg,
|
|
int eTextRep,
|
|
void *pApp,
|
|
void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
|
|
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
|
|
void (*xFinal)(sqlite3_context*)
|
|
);
|
|
int sqlite3_create_function16(
|
|
sqlite3 *db,
|
|
const void *zFunctionName,
|
|
int nArg,
|
|
int eTextRep,
|
|
void *pApp,
|
|
void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
|
|
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
|
|
void (*xFinal)(sqlite3_context*)
|
|
);
|
|
int sqlite3_create_function_v2(
|
|
sqlite3 *db,
|
|
const char *zFunctionName,
|
|
int nArg,
|
|
int eTextRep,
|
|
void *pApp,
|
|
void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
|
|
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
|
|
void (*xFinal)(sqlite3_context*),
|
|
void(*xDestroy)(void*)
|
|
);
|
|
int sqlite3_create_window_function(
|
|
sqlite3 *db,
|
|
const char *zFunctionName,
|
|
int nArg,
|
|
int eTextRep,
|
|
void *pApp,
|
|
void (*xStep)(sqlite3_context*,int,sqlite3_value**),
|
|
void (*xFinal)(sqlite3_context*),
|
|
void (*xValue)(sqlite3_context*),
|
|
void (*xInverse)(sqlite3_context*,int,sqlite3_value**),
|
|
void(*xDestroy)(void*)
|
|
);
|
|
</pre></blockquote>
|
|
<p>
|
|
These functions (collectively known as "function creation routines")
|
|
are used to add SQL functions or aggregates or to redefine the behavior
|
|
of existing SQL functions or aggregates. The only differences between
|
|
the three "sqlite3_create_function*" routines are the text encoding
|
|
expected for the second parameter (the name of the function being
|
|
created) and the presence or absence of a destructor callback for
|
|
the application data pointer. Function sqlite3_create_window_function()
|
|
is similar, but allows the user to supply the extra callback functions
|
|
needed by <a href="../windowfunctions.html#aggwinfunc">aggregate window functions</a>.</p>
|
|
|
|
<p>The first parameter is the <a href="../c3ref/sqlite3.html">database connection</a> to which the SQL
|
|
function is to be added. If an application uses more than one database
|
|
connection then application-defined SQL functions must be added
|
|
to each database connection separately.</p>
|
|
|
|
<p>The second parameter is the name of the SQL function to be created or
|
|
redefined. The length of the name is limited to 255 bytes in a UTF-8
|
|
representation, exclusive of the zero-terminator. Note that the name
|
|
length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
|
|
Any attempt to create a function with a longer name
|
|
will result in <a href="../rescode.html#misuse">SQLITE_MISUSE</a> being returned.</p>
|
|
|
|
<p>The third parameter (nArg)
|
|
is the number of arguments that the SQL function or
|
|
aggregate takes. If this parameter is -1, then the SQL function or
|
|
aggregate may take any number of arguments between 0 and the limit
|
|
set by <a href="../c3ref/limit.html">sqlite3_limit</a>(<a href="../c3ref/c_limit_attached.html#sqlitelimitfunctionarg">SQLITE_LIMIT_FUNCTION_ARG</a>). If the third
|
|
parameter is less than -1 or greater than 127 then the behavior is
|
|
undefined.</p>
|
|
|
|
<p>The fourth parameter, eTextRep, specifies what
|
|
<a href="../c3ref/c_any.html">text encoding</a> this SQL function prefers for
|
|
its parameters. The application should set this parameter to
|
|
<a href="../c3ref/c_any.html">SQLITE_UTF16LE</a> if the function implementation invokes
|
|
<a href="../c3ref/value_blob.html">sqlite3_value_text16le()</a> on an input, or <a href="../c3ref/c_any.html">SQLITE_UTF16BE</a> if the
|
|
implementation invokes <a href="../c3ref/value_blob.html">sqlite3_value_text16be()</a> on an input, or
|
|
<a href="../c3ref/c_any.html">SQLITE_UTF16</a> if <a href="../c3ref/value_blob.html">sqlite3_value_text16()</a> is used, or <a href="../c3ref/c_any.html">SQLITE_UTF8</a>
|
|
otherwise. The same SQL function may be registered multiple times using
|
|
different preferred text encodings, with different implementations for
|
|
each encoding.
|
|
When multiple implementations of the same function are available, SQLite
|
|
will pick the one that involves the least amount of data conversion.</p>
|
|
|
|
<p>The fourth parameter may optionally be ORed with <a href="../c3ref/c_deterministic.html#sqlitedeterministic">SQLITE_DETERMINISTIC</a>
|
|
to signal that the function will always return the same result given
|
|
the same inputs within a single SQL statement. Most SQL functions are
|
|
deterministic. The built-in <a href="../lang_corefunc.html#random">random()</a> SQL function is an example of a
|
|
function that is not deterministic. The SQLite query planner is able to
|
|
perform additional optimizations on deterministic functions, so use
|
|
of the <a href="../c3ref/c_deterministic.html#sqlitedeterministic">SQLITE_DETERMINISTIC</a> flag is recommended where possible.</p>
|
|
|
|
<p>The fourth parameter may also optionally include the <a href="../c3ref/c_deterministic.html#sqlitedirectonly">SQLITE_DIRECTONLY</a>
|
|
flag, which if present prevents the function from being invoked from
|
|
within VIEWs, TRIGGERs, CHECK constraints, generated column expressions,
|
|
index expressions, or the WHERE clause of partial indexes.</p>
|
|
|
|
<p><span style="background-color:#ffff90;">
|
|
For best security, the <a href="../c3ref/c_deterministic.html#sqlitedirectonly">SQLITE_DIRECTONLY</a> flag is recommended for
|
|
all application-defined SQL functions that do not need to be
|
|
used inside of triggers, view, CHECK constraints, or other elements of
|
|
the database schema. This flags is especially recommended for SQL
|
|
functions that have side effects or reveal internal application state.
|
|
Without this flag, an attacker might be able to modify the schema of
|
|
a database file to include invocations of the function with parameters
|
|
chosen by the attacker, which the application will then execute when
|
|
the database file is opened and read.
|
|
</span></p>
|
|
|
|
<p>The fifth parameter is an arbitrary pointer. The implementation of the
|
|
function can gain access to this pointer using <a href="../c3ref/user_data.html">sqlite3_user_data()</a>.</p>
|
|
|
|
<p>The sixth, seventh and eighth parameters passed to the three
|
|
"sqlite3_create_function*" functions, xFunc, xStep and xFinal, are
|
|
pointers to C-language functions that implement the SQL function or
|
|
aggregate. A scalar SQL function requires an implementation of the xFunc
|
|
callback only; NULL pointers must be passed as the xStep and xFinal
|
|
parameters. An aggregate SQL function requires an implementation of xStep
|
|
and xFinal and NULL pointer must be passed for xFunc. To delete an existing
|
|
SQL function or aggregate, pass NULL pointers for all three function
|
|
callbacks.</p>
|
|
|
|
<p>The sixth, seventh, eighth and ninth parameters (xStep, xFinal, xValue
|
|
and xInverse) passed to sqlite3_create_window_function are pointers to
|
|
C-language callbacks that implement the new function. xStep and xFinal
|
|
must both be non-NULL. xValue and xInverse may either both be NULL, in
|
|
which case a regular aggregate function is created, or must both be
|
|
non-NULL, in which case the new function may be used as either an aggregate
|
|
or aggregate window function. More details regarding the implementation
|
|
of aggregate window functions are
|
|
<a href="../windowfunctions.html#udfwinfunc">available here</a>.</p>
|
|
|
|
<p>If the final parameter to sqlite3_create_function_v2() or
|
|
sqlite3_create_window_function() is not NULL, then it is destructor for
|
|
the application data pointer. The destructor is invoked when the function
|
|
is deleted, either by being overloaded or when the database connection
|
|
closes. The destructor is also invoked if the call to
|
|
sqlite3_create_function_v2() fails. When the destructor callback is
|
|
invoked, it is passed a single argument which is a copy of the application
|
|
data pointer which was the fifth parameter to sqlite3_create_function_v2().</p>
|
|
|
|
<p>It is permitted to register multiple implementations of the same
|
|
functions with the same name but with either differing numbers of
|
|
arguments or differing preferred text encodings. SQLite will use
|
|
the implementation that most closely matches the way in which the
|
|
SQL function is used. A function implementation with a non-negative
|
|
nArg parameter is a better match than a function implementation with
|
|
a negative nArg. A function where the preferred text encoding
|
|
matches the database encoding is a better
|
|
match than a function where the encoding is different.
|
|
A function where the encoding difference is between UTF16le and UTF16be
|
|
is a closer match than a function where the encoding difference is
|
|
between UTF8 and UTF16.</p>
|
|
|
|
<p>Built-in functions may be overloaded by new application-defined functions.</p>
|
|
|
|
<p>An application-defined function is permitted to call other
|
|
SQLite interfaces. However, such calls must not
|
|
close the database connection nor finalize or reset the prepared
|
|
statement in which the 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>
|