mirrors/sqlite
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation updates: Describe recursion capabilities for the various

Browse Source 
callbacks. (CVS 5688)

FossilOrigin-Name: edd80811d702bc0d7a25199d193c04ea057df4de
This commit is contained in:
drh 2008-09-10 13:09:23 +00:00
parent 38816ecf99
commit c807542bcf
3 changed files with 83 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
manifest
View File

@ -1,5 +1,5 @@
C Avoid\sdeleting\sa\sfile\swhile\sit\sis\sstill\sopen\sin\scorrupt2.test.\sNot\sall\splatforms\ssupport\sthis.\s(CVS\s5687)
D 2008-09-10T11:28:38
C Documentation\supdates:\s\sDescribe\srecursion\scapabilities\sfor\sthe\svarious\ncallbacks.\s(CVS\s5688)
D 2008-09-10T13:09:24
F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0
F Makefile.in d15a7ebfe5e057a72a49805ffb302dbb601c8329
F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
@ -149,7 +149,7 @@ F src/random.c 11bbdf7def3746a762fbdb56c9d04648135ad6d8
F src/resolve.c a6abf83125bce0c80ba04acc27c3565155ad305c
F src/select.c eec7c5f28a0c75fdd8500630435af176bba73219
F src/shell.c d83b578a8ccdd3e0e7fef4388a0887ce9f810967
F src/sqlite.h.in 7da6a0d39221affca458b4ba305be3eb1590bb8e
F src/sqlite.h.in 81dc1e8e50fb5c7cccf0a67a34cb796efc1d2a1e
F src/sqlite3ext.h 1e3887c9bd3ae66cb599e922824b04cd0d0f2c3e
F src/sqliteInt.h 4a43cd9dcb7d5a6664a981f08e64d555acbca1bc
F src/sqliteLimit.h f435e728c6b620ef7312814d660a81f9356eb5c8
@ -634,7 +634,7 @@ F tool/speedtest16.c c8a9c793df96db7e4933f0852abb7a03d48f2e81
F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
F tool/speedtest8.c 1dbced29de5f59ba2ebf877edcadf171540374d1
F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
P 300a64b725a111ee66e38de099314f03b064c6eb
R 2fc115d04cd9022ed9994d800543641d
U danielk1977
Z 65ea31ed57297840fa2eea42aecf71f5
P 099adfd31167a78d803e2992e5f50cf4e292dd43
R 7853a8a5ccb659e8bb6ea1c2c2871c9f
U drh
Z d85bcb69ec2b69991a86141e52428a8c

2
manifest.uuid
View File

@ -1 +1 @@
099adfd31167a78d803e2992e5f50cf4e292dd43
edd80811d702bc0d7a25199d193c04ea057df4de

101
src/sqlite.h.in
View File

@ -30,7 +30,7 @@
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.397 2008/09/02 21:35:03 drh Exp $
** @(#) $Id: sqlite.h.in,v 1.398 2008/09/10 13:09:24 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
@ -1575,6 +1575,10 @@ int sqlite3_complete16(const void *sql);
** previously set handler. Note that calling [sqlite3_busy_timeout()]
** will also set or clear the busy handler.
**
** The busy callback should not take any actions which modify the
** database connection that invoked the busy handler. Any such actions
** result in undefined behavior.
**
** INVARIANTS:
**
** {H12311} The [sqlite3_busy_handler(D,C,A)] function shall replace
@ -2103,6 +2107,11 @@ void sqlite3_randomness(int N, void *P);
** previous call. Disable the authorizer by installing a NULL callback.
** The authorizer is disabled by default.
**
** The authorizer callback must not do anything that will modify
** the database connection that invoked the authorizer callback.
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
** database connections for the meaning of "modify" in this paragraph.
**
** When [sqlite3_prepare_v2()] is used to prepare a statement, the
** statement might be reprepared during [sqlite3_step()] due to a
** schema change. Hence, the application should ensure that the
@ -2327,7 +2336,12 @@ SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
**
** If the progress callback returns non-zero, the operation is
** interrupted. This feature can be used to implement a
** "Cancel" button on a GUI dialog box.
** "Cancel" button on a GUI progress dialog box.
**
** The progress handler must not do anything that will modify
** the database connection that invoked the progress handler.
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
** database connections for the meaning of "modify" in this paragraph.
**
** INVARIANTS:
**
@ -3837,7 +3851,8 @@ int sqlite3_reset(sqlite3_stmt *pStmt);
** characters. Any attempt to create a function with a longer name
** will result in [SQLITE_ERROR] being returned.
**
** The third parameter is the number of arguments that the SQL function or
** 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.
**
@ -3868,72 +3883,91 @@ int sqlite3_reset(sqlite3_stmt *pStmt);
** 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.
** 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()] interface behaves exactly
** like [sqlite3_create_function()] in every way except that it
** interprets the zFunctionName argument as zero-terminated UTF-16
** {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 registers
** {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)]
** replaces the P, F, S, and L values from any prior calls with
** 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 fails with
** a return code of [SQLITE_ERROR] if the SQL function name X is
** {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} Either F must be NULL and S and L are non-NULL or else F
** is non-NULL and S and L are NULL, otherwise
** [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR].
** {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 fails with an
** {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 fails with an
** error code of [SQLITE_ERROR] if parameter N (specifying the number
** of arguments to the SQL function being registered) is less
** {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 causes callbacks to be invoked for the SQL function
** 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 causes callbacks to be invoked for the SQL function
** named X with any number of arguments.
** 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 is preferred.
** 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 is preferred.
** 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 will always be invoked exactly once if the
** 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 are always [protected sqlite3_value] objects.
** third parameter shall be [protected sqlite3_value] objects.
*/
int sqlite3_create_function(
sqlite3 *db,
@ -4845,6 +4879,14 @@ sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
** If another function was previously registered, its
** pArg value is returned. Otherwise NULL is returned.
**
** The callback implementation must not do anything that will modify
** the database connection that invoked the callback. Any actions
** to modify the database connection must be deferred until after the
** completion of the [sqlite3_step()] call that triggered the commit
** or rollback hook in the first place.
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
** database connections for the meaning of "modify" in this paragraph.
**
** Registering a NULL function disables the callback.
**
** For the purposes of this API, a transaction is said to have been
@ -4919,6 +4961,13 @@ void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
** The update hook is not invoked when internal system tables are
** modified (i.e. sqlite_master and sqlite_sequence).
**
** The update hook implementation must not do anything that will modify
** the database connection that invoked the update hook. Any actions
** to modify the database connection must be deferred until after the
** completion of the [sqlite3_step()] call that triggered the update hook.
** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
** database connections for the meaning of "modify" in this paragraph.
**
** If another function was previously registered, its pArg value
** is returned. Otherwise NULL is returned.
**