Collation routines can be used to order results from a SELECT statement. You can define your own routine and tell QDB to use it by providing the COLLATE keyword in the ORDER BY clause.
These routines are specified in the database configuration object with the Collation::tag@library.so option, where tag is the name of the qdb_collation entry describing the collation, and library.so is the name of a DLL object containing your code (this can be an absolute path or a relative path within the library search path).
The code is set up as follows:
static int mysort(void *arg, int l1, const void *s1, int l2, const void *s2) { return(0); } struct qdb_collation ctag = { "nosort", SQLITE_UTF8, NULL, mysort, NULL };
In this case, the tag value for the structure is ctag, the collation name as visible to SQL is nosort, and the C function that implements your collation routine is called mysort() and has a NULL value for its arg argument. For more information on defining SQLite collation sequences, refer to the SQLite docs on sqlite3_create_collation(). Full details on the meaning of each qdb_collation field are given in the subsection that follows.
In this release, you can define only one collation per database. This collation must be loaded in the configuration object, by specifying a Collation:: entry that lists the name of the struct qdb_collation describing the collation, followed by the library filename.
The qdb_collation structure has these members:
struct qdb_collation { char *name; int encoding; void *arg; int (*compare)(void *, int, const void *, int, const void *); int (*setup)(void *, const void *, int, char **); };
The setup function takes this form:
int (*setup)(void *arg, const void *data, int nbytes, char **errmsg);
The function parameters are:
The function returns either a POSIX errno value or EOK (if it succeeds).
If a collation structure has a non-NULL setup entry, then this function is invoked at startup and passed NULL for data and 0 for nbytes, which gives it a hint to use the default configuration. Then, whenever you call qdb_collation(), the setup function is invoked with new data.
If a collation has no dynamic configuration, it can specify NULL for the setup entry. Note that this entry can't be changed at runtime.