Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## SQLite C Interface

## Create Or Redefine SQL Functions

>     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*)
>     );

These two 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 difference only between the two is that the second parameter, the name of the (scalar) function or aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16 for sqlite3_create_function16().

The first argument is the database connection that holds the SQL function or aggregate is to be added or redefined. If a single program uses more than one database handle internally, then SQL functions or aggregates must be added individually to each database handle with which they will be used.

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, exclusive of the zero-terminator. Note that the name length limit is in bytes, not characters. Any attempt to create a function with a longer name will result in an SQLITE_ERROR error.

The third parameter is the number of arguments that the SQL function or aggregate takes. If this parameter is negative, then the SQL function or aggregate may take any number of arguments.

The fourth parameter, eTextRep, specifies what text encoding this SQL function prefers for its parameters. Any SQL function implementation should be able to work work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be more efficient with one encoding than another. It is allowed to invoke sqlite3_create_function() or sqlite3_create_function16() multiple times with the same function but with different values of eTextRep. When multiple implementations of the same function are available, SQLite will pick the one that involves the least amount of data conversion. If there is only a single implementation which does not care what text encoding is used, then the fourth argument should be SQLITE_ANY.

The fifth parameter is an arbitrary pointer. The implementation of the function can gain access to this pointer using sqlite3_user_data().

The seventh, eighth and ninth parameters, 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 should be passed as the xStep and xFinal parameters. An aggregate SQL function requires an implementation of xStep and xFinal and NULL should be passed for xFunc. To delete an existing SQL function or aggregate, pass NULL for all three function callback.

It is permitted to register multiple implementations of the same functions with the same name but with either differing numbers of arguments or differing perferred text encodings. SQLite will use the implementation most closely matches the way in which the SQL function is used.

### Invariants:

F16103 | The sqlite3_create_function16() interface behaves exactly like sqlite3_create_function() in every way except that it interprets the zFunctionName argument as zero-terminated UTF-16 native byte order instead of as a zero-terminated UTF-8.

See also lists of Objects, Constants, and Functions.

This page last modified 2008/01/31 20:37:13 UTC