Small. Fast. Reliable.
Choose any three.

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 only difference 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 parameter is the database connection to which the SQL function is to be added. If a single program uses more than one database connection internally, then SQL functions must be added individually to each database connection.

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 SQLITE_ERROR being returned.

The third parameter (nArg) 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 callbacks.

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 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.

Built-in functions may be overloaded by new application-defined functions. The first application-defined function with a given name overrides all built-in functions in the same database connection with the same name. Subsequent application-defined functions of the same name only override prior application-defined functions that are an exact match for the number of parameters and preferred encoding.

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.

Invariants:

H16103 The sqlite3_create_function16(D,X,...) interface shall behave as sqlite3_create_function(D,X,...) in every way except that it interprets the X argument as zero-terminated UTF-16 native byte order instead of as zero-terminated UTF-8.
H16106 A successful invocation of the sqlite3_create_function(D,X,N,E,...) interface shall register or replaces callback functions in the database connection D used to implement the SQL function named X with N parameters and having a preferred text encoding of E.
H16109 A successful call to sqlite3_create_function(D,X,N,E,P,F,S,L) shall replace the P, F, S, and L values from any prior calls with the same D, X, N, and E values.
H16112 The sqlite3_create_function(D,X,...) interface shall fail if the SQL function name X is longer than 255 bytes exclusive of the zero terminator.
H16118 The sqlite3_create_function(D,X,N,E,P,F,S,L) interface shall fail unless either F is NULL and S and L are non-NULL or F is non-NULL and S and L are NULL.
H16121 The sqlite3_create_function(D,...) interface shall fails with an error code of SQLITE_BUSY if there exist prepared statements associated with the database connection D.
H16124 The sqlite3_create_function(D,X,N,...) interface shall fail with an error code of SQLITE_ERROR if parameter N is less than -1 or greater than 127.
H16127 When N is non-negative, the sqlite3_create_function(D,X,N,...) interface shall register callbacks to be invoked for the SQL function named X when the number of arguments to the SQL function is exactly N.
H16130 When N is -1, the sqlite3_create_function(D,X,N,...) interface shall register callbacks to be invoked for the SQL function named X with any number of arguments.
H16133 When calls to sqlite3_create_function(D,X,N,...) specify multiple implementations of the same function X and when one implementation has N>=0 and the other has N=(-1) the implementation with a non-zero N shall be preferred.
H16136 When calls to sqlite3_create_function(D,X,N,E,...) specify multiple implementations of the same function X with the same number of arguments N but with different encodings E, then the implementation where E matches the database encoding shall preferred.
H16139 For an aggregate SQL function created using sqlite3_create_function(D,X,N,E,P,0,S,L) the finalizer function L shall always be invoked exactly once if the step function S is called one or more times.
H16142 When SQLite invokes either the xFunc or xStep function of an application-defined SQL function or aggregate created by sqlite3_create_function() or sqlite3_create_function16(), then the array of sqlite3_value objects passed as the third parameter shall be protected sqlite3_value objects.

See also lists of Objects, Constants, and Functions.


This page last modified 2008/12/09 18:44:04 UTC