From: danielk1977 Date: Mon, 10 Jan 2005 06:39:56 +0000 (+0000) Subject: Update some documentation for version 3.1. (CVS 2188) X-Git-Tag: version-3.1.0~72 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=307a77793291dee4120158f39203b969a4e05ade;p=thirdparty%2Fsqlite.git Update some documentation for version 3.1. (CVS 2188) FossilOrigin-Name: 5b7a5a4d69be425163135698d889797d15f56492 --- diff --git a/manifest b/manifest index 9e88b08e2f..e60995f68d 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Fix\san\sassertion\sfailure\sdue\sto\sinteraction\sbetween\sthe\scount_changes\spragma\sand\striggers.\s(CVS\s2187) -D 2005-01-10T02:48:49 +C Update\ssome\sdocumentation\sfor\sversion\s3.1.\s(CVS\s2188) +D 2005-01-10T06:39:57 F Makefile.in ecf441ac5ca1ccfc8748a8a9537706e69893dfa4 F Makefile.linux-gcc a9e5a0d309fa7c38e7c14d3ecf7690879d3a5457 F README a01693e454a00cc117967e3f9fdab2d4d52e9bc1 @@ -247,14 +247,14 @@ F www/faq.tcl abe360e630d8134bc6242c5e3664969c397eac6e F www/fileformat.tcl 900c95b9633abc3dcfc384d9ddd8eb4876793059 F www/formatchng.tcl bfbf14dbf5181e771d06da7797767b0200b36d8a F www/index.tcl bb67c0d13020641d1fb4c043afa1f40fcc144d88 -F www/lang.tcl 9670e34e0a4a518b7de27a68055f49a790b6a840 +F www/lang.tcl a79b222f29cd94e11aee7bb0e69e133d55b03602 F www/lockingv3.tcl f59b19d6c8920a931f096699d6faaf61c05db55f F www/mingw.tcl d96b451568c5d28545fefe0c80bee3431c73f69c F www/nulls.tcl ec35193f92485b87b90a994a01d0171b58823fcf F www/oldnews.tcl 7aa4478e64631859770a5fe4b413919ba6ee8a08 F www/omitted.tcl 7bd62b6f0f53b60c5360895b16b3af8407bbca03 F www/opcode.tcl dafa030a5a3cc24a2f9fd4cfbfb7d7323d2151b0 -F www/pragma.tcl 8c6b5662875bccde826324fe0e37edda39b870f4 +F www/pragma.tcl f2f507d50755fea3636fbb956048aac4b14ee837 F www/quickstart.tcl 6f6f694b6139be2d967b1492eb9a6bdf7058aa60 F www/speed.tcl de99c82c4729a10b6733463636f15473c4ec95bc F www/sqlite.tcl b51fd15f0531a54874de785a9efba323eecd5975 @@ -263,7 +263,7 @@ F www/tclsqlite.tcl e73f8f8e5f20e8277619433f7970060ab01088fc F www/vdbe.tcl 095f106d93875c94b47367384ebc870517431618 F www/version3.tcl 092a01f5ef430d2c4acc0ae558d74c4bb89638a0 F www/whentouse.tcl c3b50d3ac31c54be2a1af9b488a89d22f1e6e746 -P ad10953799f3aa15fde41cbbd5911a3b56c326ec -R 1ac4cd5c08a83609a7da947b3ea99143 +P 6c7bec1b3aee0287e30f43c1d6a7b67b1c47e774 +R 7068bc64df143e31a5d1b0a4a0ebbc69 U danielk1977 -Z 66f70bfca0a624fd768df4e664b868f3 +Z 5c1fa24d0389e66faa5fc6c7963ab21a diff --git a/manifest.uuid b/manifest.uuid index 1a026f125c..6996d4c1bf 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -6c7bec1b3aee0287e30f43c1d6a7b67b1c47e774 \ No newline at end of file +5b7a5a4d69be425163135698d889797d15f56492 \ No newline at end of file diff --git a/www/lang.tcl b/www/lang.tcl index 57d43effad..97e2ff2990 100644 --- a/www/lang.tcl +++ b/www/lang.tcl @@ -1,7 +1,7 @@ # # Run this Tcl script to generate the lang-*.html files. # -set rcsid {$Id: lang.tcl,v 1.80 2004/11/21 01:02:01 drh Exp $} +set rcsid {$Id: lang.tcl,v 1.81 2005/01/10 06:39:57 danielk1977 Exp $} source common.tcl if {[llength $argv]>0} { @@ -887,7 +887,8 @@ Section expression expr Syntax {expr} { | - | + [ESCAPE ] | + | | ( ) | | @@ -904,7 +905,9 @@ Syntax {expr} { ( ) | CASE [] LP WHEN THEN RPPLUS [ELSE ] END } {like-op} { -LIKE | GLOB | NOT LIKE | NOT GLOB +LIKE | NOT LIKE +} {glob-op} { +GLOB | NOT GLOB } puts { @@ -950,21 +953,48 @@ operand modulo its right operand.

" puts { +

The LIKE operator does a pattern matching comparison. The operand +to the right contains the pattern, the left hand operand contains the +string to match against the pattern. +} +puts "A percent symbol [Operator %] in the pattern matches any +sequence of zero or more characters in the string. An underscore +[Operator _] in the pattern matches any single character in the +string. Any other character matches itself or it's lower/upper case +equivalent (i.e. case-insensitive matching). (A bug: SQLite only +understands upper/lower case for 7-bit Latin characters. Hence the +LIKE operator is case sensitive for 8-bit iso8859 characters or UTF-8 +characters. For example, the expression 'a' LIKE 'A' +is TRUE but 'æ' LIKE 'Æ' is FALSE.).

" + +puts { +

If the optional ESCAPE clause is present, then the expression +following the ESCAPE keyword must evaluate to a string consisting of +a single character. This character may be used in the LIKE pattern +to include literal percent or underscore characters. The escape +character followed by a percent symbol, underscore or itself matches a +literal percent symbol, underscore or escape character in the string, +respectively. The infix LIKE operator is implemented by calling the +user function like(X,Y).

+} + +puts {

The LIKE operator does a wildcard comparison. The operand to the right contains the wildcards.} puts "A percent symbol [Operator %] in the right operand matches any sequence of zero or more characters on the left. An underscore [Operator _] on the right matches any single character on the left." -puts {The LIKE operator is -not case sensitive and will match upper case characters on one -side against lower case characters on the other. + +puts { +The LIKE operator is not case sensitive and will match upper case +characters on one side against lower case characters on the other. (A bug: SQLite only understands upper/lower case for 7-bit Latin -characters. Hence the LIKE operator is case sensitive for -8-bit iso8859 characters or UTF-8 characters. For example, -the expression 'a' LIKE 'A' is TRUE but -'æ' LIKE 'Æ' is FALSE.). The infix -LIKE operator is identical the user function +characters. Hence the LIKE operator is case sensitive for 8-bit +iso8859 characters or UTF-8 characters. For example, the expression +'a' LIKE 'A' is TRUE but +'æ' LIKE 'Æ' is FALSE.). The infix LIKE +operator is identical the user function like(X,Y).

@@ -1067,13 +1097,20 @@ characters is returned, not the number of bytes. -like(X,Y) -This function is used to implement the -"X LIKE Y" syntax of SQL. The -sqlite_create_function() -interface can -be used to override this function and thereby change the operation -of the LIKE operator. +like(X,Y [,Z]) + +This function is used to implement the "X LIKE Y [ESCAPE Z]" +syntax of SQL. If the optional ESCAPE clause is present, then the +user-function is invoked with three arguments. Otherwise, it is +invoked with two arguments only. The + +sqlite_create_function() interface can be used to override this +function and thereby change the operation of the LIKE operator. When doing this, it may be important +to override both the two and three argument versions of the like() +function. Otherwise, different code may be called to implement the +LIKE operator depending on whether or not an ESCAPE clause was +specified. diff --git a/www/pragma.tcl b/www/pragma.tcl index 3df1d0f9c4..aaefbc454b 100644 --- a/www/pragma.tcl +++ b/www/pragma.tcl @@ -1,7 +1,7 @@ # # Run this Tcl script to generate the pragma.html file. # -set rcsid {$Id: pragma.tcl,v 1.7 2004/12/20 19:01:34 tpoindex Exp $} +set rcsid {$Id: pragma.tcl,v 1.8 2005/01/10 06:39:57 danielk1977 Exp $} source common.tcl header {Pragma statements supported by SQLite} @@ -108,6 +108,17 @@ puts { the default_cache_size pragma to check the cache size permanently.

+ +

  • PRAGMA count_changes; +
    PRAGMA count_changes =     0 | 1;

    +

    Query or change the count-changes flag. Normally, when the + count-changes flag is not set, INSERT, UPDATE and DELETE statements + return no data. When count-changes is set, each of these commands + returns a single row of data consisting of one integer value - the + number of rows inserted, modified or deleted by the command. The + returned change count does not include any insertions, modifications + or deletions performed by triggers.

    +

  • PRAGMA default_cache_size;
    PRAGMA default_cache_size =     Number-of-pages;

    @@ -121,13 +132,98 @@ puts { you can set the cache size once and that setting is retained and reused every time you reopen the database.

    • - -

  • PRAGMA default_synchronous; -
    PRAGMA default_synchronous = FULL;     (2) -
    PRAGMA default_synchronous = NORMAL;     (1) -
    PRAGMA default_synchronous = OFF;     (0)

    -

    Query or change the setting of the "synchronous" flag in - the database. The first (query) form will return the setting as an + +

  • PRAGMA empty_result_callbacks; +
    PRAGMA empty_result_callbacks =     0 | 1;

    +

    Query or change the empty-result-callbacks flag.

    +

    The empty-result-callbacks flag affects the sqlite3_exec API only. + Normally, when the empty-result-callbacks flag is cleared, the + callback function supplied to the sqlite3_exec() call is not invoked + for commands that return zero rows of data. When empty-result-callbacks + is set in this situation, the callback function is invoked exactly once, + with the third parameter set to 0 (NULL). This is to enable programs + that use the sqlite3_exec() API to retrieve column-names even when + a query returns no data. +

    + + +

  • PRAGMA encoding; +
    PRAGMA encoding = "UTF-8"; +
    PRAGMA encoding = "UTF-16"; +
    PRAGMA encoding = "UTF-16le"; +
    PRAGMA encoding = "UTF-16be";

    +

    In it's first form, if the main database has already been + created, then this pragma returns the text encoding used by the + main database, one of "UTF-8", "UTF-16le" (little-endian UTF-16 + encoding) or "UTF-16be" (big-endian UTF-16 encoding). If the main + database has not already been created, then the value returned is the + text encoding that will be used to create the main database, if + it is created by this session.

    +

    The second and subsequent forms of this pragma are only useful if + the main database has not already been created. In this case the + pragma sets the encoding that the main database will be created with if + it is created by this session. The string "UTF-16" is interpreted + as "UTF-16 encoding using native machine byte-ordering".

    +

    Databases created by the ATTACH command always use the same encoding + as the main database.

    +
    • + + +

  • PRAGMA full_column_names; +
    PRAGMA full_column_names =     0 | 1;

    +

    Query or change the full-column-names flag. This flag affects + the way SQLite names columns of data returned by SELECT statements + when the expression for the column is a table-column name or the + wildcard "*". Normally, such result columns are named + . if the SELECT statement joins two or + more tables together, or simply if the SELECT + statement queries a single table. When the full-column-names flag + is set, such columns are always named ., + regardless of whether or not a join is performed. +

    +

    If both the short-column-names and full-column-names are set, + then the behaviour associated with the full-column-names flag is + exhibited. +

    +
    • + + +

  • PRAGMA page_size; +
    PRAGMA page_size =     bytes;

    +

    Query or set the page-size of the database. The page-size + may only be set if the database has not yet been created. The page + size must be a power of two greater than or equal to 512 and less + than or equal to 8192. The upper limit may be modified by setting + the value of macro SQLITE_MAX_PAGE_SIZE during compilation. +

    +
    • + + +

  • PRAGMA full_column_names; +
    PRAGMA full_column_names =     0 | 1;

    +

    Query or change the short-column-names flag. This flag affects + the way SQLite names columns of data returned by SELECT statements + when the expression for the column is a table-column name or the + wildcard "*". Normally, such result columns are named + . if the SELECT statement joins two or + more tables together, or simply if the SELECT + statement queries a single table. When the short-column-names flag + is set, such columns are always named , regardless of + whether or not a join is performed. +

    +

    If both the short-column-names and full-column-names are set, + then the behaviour associated with the full-column-names flag is + exhibited. +

    +
    • + + +

  • PRAGMA synchronous; +
    PRAGMA synchronous = FULL;     (2) +
    PRAGMA synchronous = NORMAL;     (1) +
    PRAGMA synchronous = OFF;     (0)

    +

    Query or change the setting of the "synchronous" flag. + The first (query) form will return the setting as an integer. When synchronous is FULL (2), the SQLite database engine will pause at critical moments to make sure that data has actually been written to the disk surface before continuing. This ensures that if @@ -148,57 +244,8 @@ puts { crashes or the computer loses power before that data has been written to the disk surface. On the other hand, some operations are as much as 50 or more times faster with synchronous OFF. -

    -

    This pragma changes the synchronous mode persistently. Once changed, - the mode stays as set even if the database is closed and reopened. The - synchronous pragma does the same - thing but only applies the setting to the current session. -

    • - -

  • PRAGMA default_temp_store; -
    PRAGMA default_temp_store = DEFAULT;     (0) -
    PRAGMA default_temp_store = MEMORY;     (2) -
    PRAGMA default_temp_store = FILE;     (1)

    -

    Query or change the setting of the "temp_store" flag stored in - the database. When temp_store is DEFAULT (0), the compile-time value - of the symbol TEMP_STORE is used for the temporary database. - When temp_store is MEMORY (2), an in-memory database is used. - When temp_store is FILE (1), a temporary database file on disk will be used. - It is possible for the library compile-time symbol TEMP_STORE to override - this setting. The following table summarizes this:

    - - - - - - - - - - - -
    TEMP_STOREtemp_storetemp database location
    0anyfile
    10file
    11file
    12memory
    20memory
    21file
    22memory
    3anymemory
    - -

    This pragma changes the temp_store mode for whenever the database - is opened in the future. The temp_store mode for the current session - is unchanged. Use the - temp_store pragma to change the - temp_store mode for the current session.

    • - - -

  • PRAGMA synchronous; -
    PRAGMA synchronous = FULL;     (2) -
    PRAGMA synchronous = NORMAL;     (1) -
    PRAGMA synchronous = OFF;     (0)

    -

    Query or change the setting of the "synchronous" flag affecting - the database for the duration of the current database connection. - The synchronous flag reverts to its default value when the database - is closed and reopened. For additional information on the synchronous - flag, see the description of the - default_synchronous pragma.

    -

  • PRAGMA temp_store; @@ -211,14 +258,41 @@ puts { is closed and reopened. For additional information on the temp_store flag, see the description of the default_temp_store pragma. Note that it is possible for - the library compile-time options to override this setting. See - PRAGMA temp_store_directory - for further temporary storage options when FILE is specified.

    + the library compile-time options to override this setting. -

    When the temp_store setting is changed, all existing temporary - tables, indices, triggers, and viewers are immediately deleted. -

    -
    • + +

  • PRAGMA temp_store; +
    PRAGMA temp_store = DEFAULT;     (0) +
    PRAGMA temp_store = MEMORY;     (2) +
    PRAGMA temp_store = FILE;     (1)

    +

    Query or change the setting of the "temp_store" parameter. + When temp_store is DEFAULT (0), the compile-time value of the + symbol TEMP_STORE is used for the temporary database. When + temp_store is MEMORY (2), an in-memory database is used. + When temp_store is FILE (1), a temporary database file on disk + will be used. See PRAGMA + temp_store_directory for further temporary storage options when + FILE is specified. When the temp_store setting is changed, + all existing temporary tables, indices, triggers, and viewers are + immediately deleted.

    + +

    It is possible for the library compile-time symbol + TEMP_STORE to override this setting. The following table summarizes + this:

    + + + + + + + + + + + +
    TEMP_STOREtemp_storetemp database location
    0anyfile
    10file
    11file
    12memory
    20memory
    21file
    22memory
    3anymemory
    +
    • +

  • PRAGMA temp_store_directory;