Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | More documentation spellcheck and cleanup. No changes to code. (CVS 5263) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
3edfc64f27ba50ba43b79435b3f5d273 |
User & Date: | mihailim 2008-06-21 16:47:09.000 |
Context
2008-06-21
| ||
18:02 | More documentation spellcheck and cleanup. No changes to code. (CVS 5264) (check-in: 9ae03f5629 user: mihailim tags: trunk) | |
16:47 | More documentation spellcheck and cleanup. No changes to code. (CVS 5263) (check-in: 3edfc64f27 user: mihailim tags: trunk) | |
13:35 | More documentation spellcheck and cleanup. No changes to code. (CVS 5262) (check-in: 47b7b05e55 user: mihailim tags: trunk) | |
Changes
Changes to src/sqlite.h.in.
︙ | ︙ | |||
26 27 28 29 30 31 32 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** | | | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** ** @(#) $Id: sqlite.h.in,v 1.346 2008/06/21 16:47:09 mihailim Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ #include <stdarg.h> /* Needed for the definition of va_list */ /* ** Make sure we can call this stuff from C++. |
︙ | ︙ | |||
344 345 346 347 348 349 350 | ** the E parameter is not NULL, then [sqlite3_exec()] shall store ** in *E an appropriate error message written into memory obtained ** from [sqlite3_malloc()]. ** ** {F12134} The [sqlite3_exec(D,S,C,A,E)] routine shall set the value of ** *E to NULL if E is not NULL and there are no errors. ** | | | 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 | ** the E parameter is not NULL, then [sqlite3_exec()] shall store ** in *E an appropriate error message written into memory obtained ** from [sqlite3_malloc()]. ** ** {F12134} The [sqlite3_exec(D,S,C,A,E)] routine shall set the value of ** *E to NULL if E is not NULL and there are no errors. ** ** {F12137} The [sqlite3_exec(D,S,C,A,E)] function shall set the [error code] ** and message accessible via [sqlite3_errcode()], ** [sqlite3_errmsg()], and [sqlite3_errmsg16()]. ** ** {F12138} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL or an ** empty string or contains nothing other than whitespace, comments, ** and/or semicolons, then results of [sqlite3_errcode()], ** [sqlite3_errmsg()], and [sqlite3_errmsg16()] |
︙ | ︙ | |||
380 381 382 383 384 385 386 387 388 389 390 391 392 393 | void *, /* 1st argument to callback */ char **errmsg /* Error msg written here */ ); /* ** CAPI3REF: Result Codes {F10210} ** KEYWORDS: SQLITE_OK {error code} {error codes} ** ** Many SQLite functions return an integer result code from the set shown ** here in order to indicates success or failure. ** ** See also: [SQLITE_IOERR_READ | extended result codes] */ #define SQLITE_OK 0 /* Successful result */ | > | 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 | void *, /* 1st argument to callback */ char **errmsg /* Error msg written here */ ); /* ** CAPI3REF: Result Codes {F10210} ** KEYWORDS: SQLITE_OK {error code} {error codes} ** KEYWORDS: {result code} {result codes} ** ** Many SQLite functions return an integer result code from the set shown ** here in order to indicates success or failure. ** ** See also: [SQLITE_IOERR_READ | extended result codes] */ #define SQLITE_OK 0 /* Successful result */ |
︙ | ︙ | |||
421 422 423 424 425 426 427 | #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ /* end-of-error-codes */ /* ** CAPI3REF: Extended Result Codes {F10220} ** KEYWORDS: {extended error code} {extended error codes} | | | 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 | #define SQLITE_ROW 100 /* sqlite3_step() has another row ready */ #define SQLITE_DONE 101 /* sqlite3_step() has finished executing */ /* end-of-error-codes */ /* ** CAPI3REF: Extended Result Codes {F10220} ** KEYWORDS: {extended error code} {extended error codes} ** KEYWORDS: {extended result code} {extended result codes} ** ** In its default configuration, SQLite API routines return one of 26 integer ** [SQLITE_OK | result codes]. However, experience has shown that many of ** these result codes are too coarse-grained. They do not provide as ** much information about problems as programmers might like. In an effort to ** address this, newer versions of SQLite (version 3.3.8 and later) include ** support for additional result codes that provide more detailed information |
︙ | ︙ | |||
1114 1115 1116 1117 1118 1119 1120 | #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ /* ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200} ** ** The sqlite3_extended_result_codes() routine enables or disables the | | | < | 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 | #define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */ #define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */ /* ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200} ** ** The sqlite3_extended_result_codes() routine enables or disables the ** [extended result codes] feature of SQLite. The extended result ** codes are disabled by default for historical compatibility considerations. ** ** INVARIANTS: ** ** {F12201} Each new [database connection] shall have the ** [extended result codes] feature disabled by default. ** ** {F12202} The [sqlite3_extended_result_codes(D,F)] interface shall enable |
︙ | ︙ | |||
2220 2221 2222 2223 2224 2225 2226 | ** filename argument. The filename argument is interpreted as UTF-8 for ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte ** order for sqlite3_open16(). A [database connection] handle is usually ** returned in *ppDb, even if an error occurs. The only exception is that ** if SQLite is unable to allocate memory to hold the [sqlite3] object, ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3] ** object. If the database is opened (and/or created) successfully, then | | | 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 | ** filename argument. The filename argument is interpreted as UTF-8 for ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte ** order for sqlite3_open16(). A [database connection] handle is usually ** returned in *ppDb, even if an error occurs. The only exception is that ** if SQLite is unable to allocate memory to hold the [sqlite3] object, ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3] ** object. If the database is opened (and/or created) successfully, then ** [SQLITE_OK] is returned. Otherwise an [error code] is returned. The ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain ** an English language description of the error. ** ** The default encoding for the database will be UTF-8 if ** sqlite3_open() or sqlite3_open_v2() is called and ** UTF-16 in the native byte order if sqlite3_open16() is used. ** |
︙ | ︙ | |||
2340 2341 2342 2343 2344 2345 2346 | ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required ** in sqlite3_open_v2()?</todo> ** ** {F12721} The [database connection] created by [sqlite3_open_v2(F,D,G,V)] ** will use the [sqlite3_vfs] object identified by the V parameter, ** or the default [sqlite3_vfs] object if V is a NULL pointer. ** | | | < | 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 | ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required ** in sqlite3_open_v2()?</todo> ** ** {F12721} The [database connection] created by [sqlite3_open_v2(F,D,G,V)] ** will use the [sqlite3_vfs] object identified by the V parameter, ** or the default [sqlite3_vfs] object if V is a NULL pointer. ** ** {F12723} Two [database connections] will share a common cache if both were ** opened with the same VFS while [shared cache mode] was enabled and ** if both filenames compare equal using memcmp() after having been ** processed by the [sqlite3_vfs | xFullPathname] method of the VFS. */ int sqlite3_open( const char *filename, /* Database filename (UTF-8) */ sqlite3 **ppDb /* OUT: SQLite db handle */ ); |
︙ | ︙ | |||
2364 2365 2366 2367 2368 2369 2370 | int flags, /* Flags */ const char *zVfs /* Name of VFS module to use */ ); /* ** CAPI3REF: Error Codes And Messages {F12800} ** | | < | | | | | < | | < | 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 | int flags, /* Flags */ const char *zVfs /* Name of VFS module to use */ ); /* ** CAPI3REF: Error Codes And Messages {F12800} ** ** The sqlite3_errcode() interface returns the numeric [result code] or ** [extended result code] for the most recent failed sqlite3_* API call ** associated with a [database connection]. If a prior API call failed ** but the most recent API call succeeded, the return value from ** sqlite3_errcode() is undefined. ** ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language ** text that describes the error, as either UTF8 or UTF16 respectively. ** Memory to hold the error message string is managed internally. ** The application does not need to worry about freeing the result. ** However, the error string might be overwritten or deallocated by ** subsequent calls to other SQLite interface functions. ** ** INVARIANTS: ** ** {F12801} The [sqlite3_errcode(D)] interface returns the numeric ** [result code] or [extended result code] for the most recently ** failed interface call associated with the [database connection] D. ** ** {F12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)] ** interfaces return English-language text that describes ** the error in the mostly recently failed interface call, ** encoded as either UTF8 or UTF16 respectively. ** ** {F12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()] |
︙ | ︙ | |||
2413 2414 2415 2416 2417 2418 2419 | const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*); /* ** CAPI3REF: SQL Statement Object {F13000} ** KEYWORDS: {prepared statement} {prepared statements} ** | | | | | | | 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 | const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*); /* ** CAPI3REF: SQL Statement Object {F13000} ** KEYWORDS: {prepared statement} {prepared statements} ** ** An instance of this object represents a single SQL statement. ** This object is variously known as a "prepared statement" or a ** "compiled SQL statement" or simply as a "statement". ** ** The life of a statement object goes something like this: ** ** <ol> ** <li> Create the object using [sqlite3_prepare_v2()] or a related ** function. ** <li> Bind values to [host parameters] using the sqlite3_bind_*() ** interfaces. ** <li> Run the SQL by calling [sqlite3_step()] one or more times. ** <li> Reset the statement using [sqlite3_reset()] then go back ** to step 2. Do this zero or more times. ** <li> Destroy the object using [sqlite3_finalize()]. ** </ol> ** ** Refer to documentation on individual methods above for additional |
︙ | ︙ | |||
2447 2448 2449 2450 2451 2452 2453 | ** [database connection] whose limit is to be set or queried. The ** second parameter is one of the [limit categories] that define a ** class of constructs to be size limited. The third parameter is the ** new limit for that construct. The function returns the old limit. ** ** If the new limit is a negative number, the limit is unchanged. ** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper | | | | < | | | | | | | < | 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 | ** [database connection] whose limit is to be set or queried. The ** second parameter is one of the [limit categories] that define a ** class of constructs to be size limited. The third parameter is the ** new limit for that construct. The function returns the old limit. ** ** If the new limit is a negative number, the limit is unchanged. ** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper ** bound set by a compile-time C preprocessor macro named SQLITE_MAX_XYZ. ** (The "_LIMIT_" in the name is changed to "_MAX_".) ** Attempts to increase a limit above its hard upper bound are ** silently truncated to the hard upper limit. ** ** Run time limits are intended for use in applications that manage ** both their own internal database and also databases that are controlled ** by untrusted external sources. An example application might be a ** webbrowser that has its own databases for storing history and ** separate databases controlled by JavaScript applications downloaded ** off the Internet. The internal databases can be given the ** large, default limits. Databases managed by external sources can ** be given much smaller limits designed to prevent a denial of service ** attack. Developers might also want to use the [sqlite3_set_authorizer()] ** interface to further control untrusted SQL. The size of the database ** created by an untrusted script can be contained using the ** [max_page_count] [PRAGMA]. ** ** This interface is currently considered experimental and is subject ** to change or removal without prior notice. ** ** INVARIANTS: ** ** {F12762} A successful call to [sqlite3_limit(D,C,V)] where V is ** positive changes the limit on the size of construct C in the ** [database connection] D to the lesser of V and the hard upper ** bound on the size of C that is set at compile-time. ** ** {F12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative ** leaves the state of the [database connection] D unchanged. ** ** {F12769} A successful call to [sqlite3_limit(D,C,V)] returns the ** value of the limit on the size of construct C in the ** [database connection] D as it was prior to the call. */ int sqlite3_limit(sqlite3*, int id, int newVal); /* ** CAPI3REF: Run-Time Limit Categories {F12790} ** KEYWORDS: {limit category} {limit categories} ** ** These constants define various aspects of a [database connection] ** that can be limited in size by calls to [sqlite3_limit()]. ** The meanings of the various limits are as follows: ** ** <dl> ** <dt>SQLITE_LIMIT_LENGTH</dt> ** <dd>The maximum size of any string or BLOB or table row.<dd> ** ** <dt>SQLITE_LIMIT_SQL_LENGTH</dt> ** <dd>The maximum length of an SQL statement.</dd> ** ** <dt>SQLITE_LIMIT_COLUMN</dt> ** <dd>The maximum number of columns in a table definition or in the ** result set of a SELECT or the maximum number of columns in an index |
︙ | ︙ | |||
2544 2545 2546 2547 2548 2549 2550 2551 2552 | #define SQLITE_LIMIT_FUNCTION_ARG 6 #define SQLITE_LIMIT_ATTACHED 7 #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 #define SQLITE_LIMIT_VARIABLE_NUMBER 9 /* ** CAPI3REF: Compiling An SQL Statement {F13010} ** ** To execute an SQL query, it must first be compiled into a byte-code | > | | | | | | | | < | | | | | | | | | < | | < | | < | < | | | | | | < | | | | | | | 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 | #define SQLITE_LIMIT_FUNCTION_ARG 6 #define SQLITE_LIMIT_ATTACHED 7 #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8 #define SQLITE_LIMIT_VARIABLE_NUMBER 9 /* ** CAPI3REF: Compiling An SQL Statement {F13010} ** KEYWORDS: {SQL statement compiler} ** ** To execute an SQL query, it must first be compiled into a byte-code ** program using one of these routines. ** ** The first argument, "db", is a [database connection] obtained from a ** prior call to [sqlite3_open()], [sqlite3_open_v2()] or [sqlite3_open16()]. ** ** The second argument, "zSql", is the statement to be compiled, encoded ** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2() ** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2() ** use UTF-16.{END} ** ** If the nByte argument is less than zero, then zSql is read up to the ** first zero terminator. If nByte is non-negative, then it is the maximum ** number of bytes read from zSql. When nByte is non-negative, the ** zSql string ends at either the first '\000' or '\u0000' character or ** the nByte-th byte, whichever comes first. If the caller knows ** that the supplied string is nul-terminated, then there is a small ** performance advantage to be gained by passing an nByte parameter that ** is equal to the number of bytes in the input string <i>including</i> ** the nul-terminator bytes.{END} ** ** *pzTail is made to point to the first byte past the end of the ** first SQL statement in zSql. These routines only compile the first ** statement in zSql, so *pzTail is left pointing to what remains ** uncompiled. ** ** *ppStmt is left pointing to a compiled [prepared statement] that can be ** executed using [sqlite3_step()]. If there is an error, *ppStmt is set ** to NULL. If the input text contains no SQL (if the input is an empty ** string or a comment) then *ppStmt is set to NULL. ** {U13018} The calling procedure is responsible for deleting the compiled ** SQL statement using [sqlite3_finalize()] after it has finished with it. ** ** On success, [SQLITE_OK] is returned, otherwise an [error code] is returned. ** ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are ** recommended for all new programs. The two older interfaces are retained ** for backwards compatibility, but their use is discouraged. ** In the "v2" interfaces, the prepared statement ** that is returned (the [sqlite3_stmt] object) contains a copy of the ** original SQL text. {END} This causes the [sqlite3_step()] interface to ** behave a differently in two ways: ** ** <ol> ** <li> ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it ** always used to do, [sqlite3_step()] will automatically recompile the SQL ** statement and try to run it again. If the schema has changed in ** a way that makes the statement no longer valid, [sqlite3_step()] will still ** return [SQLITE_SCHEMA]. But unlike the legacy behavior, [SQLITE_SCHEMA] is ** now a fatal error. Calling [sqlite3_prepare_v2()] again will not make the ** error go away. Note: use [sqlite3_errmsg()] to find the text ** of the parsing error that results in an [SQLITE_SCHEMA] return. {END} ** </li> ** ** <li> ** When an error occurs, [sqlite3_step()] will return one of the detailed ** [error codes] or [extended error codes]. The legacy behavior was that ** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code ** and you would have to make a second call to [sqlite3_reset()] in order ** to find the underlying cause of the problem. With the "v2" prepare ** interfaces, the underlying reason for the error is returned immediately. ** </li> ** </ol> ** ** INVARIANTS: ** ** {F13011} The [sqlite3_prepare(db,zSql,...)] and ** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the ** text in their zSql parameter as UTF-8. ** ** {F13012} The [sqlite3_prepare16(db,zSql,...)] and ** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the ** text in their zSql parameter as UTF-16 in the native byte order. ** ** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] ** and its variants is less than zero, the SQL text is ** read from zSql is read up to the first zero terminator. ** ** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)] ** and its variants is non-negative, then at most nBytes bytes of ** SQL text is read from zSql. ** ** {F13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants ** if the zSql input text contains more than one SQL statement ** and pzTail is not NULL, then *pzTail is made to point to the ** first byte past the end of the first SQL statement in zSql. ** <todo>What does *pzTail point to if there is one statement?</todo> ** ** {F13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)] ** or one of its variants writes into *ppStmt a pointer to a new ** [prepared statement] or a pointer to NULL if zSql contains ** nothing other than whitespace or comments. ** ** {F13019} The [sqlite3_prepare_v2()] interface and its variants return ** [SQLITE_OK] or an appropriate [error code] upon failure. ** ** {F13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its ** variants returns an error (any value other than [SQLITE_OK]), ** they first set *ppStmt to NULL. */ int sqlite3_prepare( sqlite3 *db, /* Database handle */ const char *zSql, /* SQL statement, UTF-8 encoded */ int nByte, /* Maximum length of zSql in bytes. */ sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const char **pzTail /* OUT: Pointer to unused portion of zSql */ |
︙ | ︙ | |||
2684 2685 2686 2687 2688 2689 2690 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const void **pzTail /* OUT: Pointer to unused portion of zSql */ ); /* ** CAPIREF: Retrieving Statement SQL {F13100} ** | | | > | < | | < | | < | | < | | < | | | | | | < | | | < < | | | | < | | < | < | | | > > | | < | | < | | | > | | | | < | | | | | | | | | < | | | | | | | | > | | | | | | | | | | | | | < | | > | | | 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 | sqlite3_stmt **ppStmt, /* OUT: Statement handle */ const void **pzTail /* OUT: Pointer to unused portion of zSql */ ); /* ** CAPIREF: Retrieving Statement SQL {F13100} ** ** This interface can be used to retrieve a saved copy of the original ** SQL text used to create a [prepared statement] if that statement was ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()]. ** ** INVARIANTS: ** ** {F13101} If the [prepared statement] passed as the argument to ** [sqlite3_sql()] was compiled using either [sqlite3_prepare_v2()] or ** [sqlite3_prepare16_v2()], then [sqlite3_sql()] returns ** a pointer to a zero-terminated string containing a UTF-8 rendering ** of the original SQL statement. ** ** {F13102} If the [prepared statement] passed as the argument to ** [sqlite3_sql()] was compiled using either [sqlite3_prepare()] or ** [sqlite3_prepare16()], then [sqlite3_sql()] returns a NULL pointer. ** ** {F13103} The string returned by [sqlite3_sql(S)] is valid until the ** [prepared statement] S is deleted using [sqlite3_finalize(S)]. */ const char *sqlite3_sql(sqlite3_stmt *pStmt); /* ** CAPI3REF: Dynamically Typed Value Object {F15000} ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value} ** ** SQLite uses the sqlite3_value object to represent all values ** that can be stored in a database table. SQLite uses dynamic typing ** for the values it stores. Values stored in sqlite3_value objects ** can be integers, floating point values, strings, BLOBs, or NULL. ** ** An sqlite3_value object may be either "protected" or "unprotected". ** Some interfaces require a protected sqlite3_value. Other interfaces ** will accept either a protected or an unprotected sqlite3_value. ** Every interface that accepts sqlite3_value arguments specifies ** whether or not it requires a protected sqlite3_value. ** ** The terms "protected" and "unprotected" refer to whether or not ** a mutex is held. A internal mutex is held for a protected ** sqlite3_value object but no mutex is held for an unprotected ** sqlite3_value object. If SQLite is compiled to be single-threaded ** (with SQLITE_THREADSAFE=0 and with [sqlite3_threadsafe()] returning 0) ** then there is no distinction between protected and unprotected ** sqlite3_value objects and they can be used interchangeably. However, ** for maximum code portability it is recommended that applications ** still make the distinction between between protected and unprotected ** sqlite3_value objects even if they are single threaded. ** ** The sqlite3_value objects that are passed as parameters into the ** implementation of [application-defined SQL functions] are protected. ** The sqlite3_value object returned by ** [sqlite3_column_value()] is unprotected. ** Unprotected sqlite3_value objects may only be used with ** [sqlite3_result_value()] and [sqlite3_bind_value()]. ** The [sqlite3_value_blob | sqlite3_value_type()] family of ** interfaces require protected sqlite3_value objects. */ typedef struct Mem sqlite3_value; /* ** CAPI3REF: SQL Function Context Object {F16001} ** ** The context in which an SQL function executes is stored in an ** sqlite3_context object. A pointer to an sqlite3_context object ** is always first parameter to [application-defined SQL functions]. ** The application-defined SQL function implementation will pass this ** pointer through into calls to [sqlite3_result_int | sqlite3_result()], ** [sqlite3_aggregate_context()], [sqlite3_user_data()], ** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()], ** and/or [sqlite3_set_auxdata()]. */ typedef struct sqlite3_context sqlite3_context; /* ** CAPI3REF: Binding Values To Prepared Statements {F13500} ** KEYWORDS: {host parameter} {host parameters} {host parameter name} ** KEYWORDS: {SQL parameter} {SQL parameters} ** ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants, ** literals may be replaced by a parameter in one of these forms: ** ** <ul> ** <li> ? ** <li> ?NNN ** <li> :VVV ** <li> @VVV ** <li> $VVV ** </ul> ** ** In the parameter forms shown above NNN is an integer literal, ** and VVV is an alpha-numeric parameter name. The values of these ** parameters (also called "host parameter names" or "SQL parameters") ** can be set using the sqlite3_bind_*() routines defined here. ** ** The first argument to the sqlite3_bind_*() routines is always ** a pointer to the [sqlite3_stmt] object returned from ** [sqlite3_prepare_v2()] or its variants. ** ** The second argument is the index of the SQL parameter to be set. ** The leftmost SQL parameter has an index of 1. When the same named ** SQL parameter is used more than once, second and subsequent ** occurrences have the same index as the first occurrence. ** The index for named parameters can be looked up using the ** [sqlite3_bind_parameter_name()] API if desired. The index ** for "?NNN" parameters is the value of NNN. ** The NNN value must be between 1 and the compile-time ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999). ** ** The third argument is the value to bind to the parameter. ** ** In those routines that have a fourth argument, its value is the ** number of bytes in the parameter. To be clear: the value is the ** number of <u>bytes</u> in the value, not the number of characters. ** If the fourth parameter is negative, the length of the string is ** the number of bytes up to the first zero terminator. ** ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or ** string after SQLite has finished with it. If the fifth argument is ** the special value [SQLITE_STATIC], then SQLite assumes that the ** information is in static, unmanaged space and does not need to be freed. ** If the fifth argument has the value [SQLITE_TRANSIENT], then ** SQLite makes its own private copy of the data immediately, before ** the sqlite3_bind_*() routine returns. ** ** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that ** is filled with zeroes. A zeroblob uses a fixed amount of memory ** (just an integer to hold its size) while it is being processed. ** Zeroblobs are intended to serve as placeholders for BLOBs whose ** content is later written using ** [sqlite3_blob_open | incremental BLOB I/O] routines. ** A negative value for the zeroblob results in a zero-length BLOB. ** ** The sqlite3_bind_*() routines must be called after ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and ** before [sqlite3_step()]. ** Bindings are not cleared by the [sqlite3_reset()] routine. ** Unbound parameters are interpreted as NULL. ** ** These routines return [SQLITE_OK] on success or an error code if ** anything goes wrong. [SQLITE_RANGE] is returned if the parameter ** index is out of range. [SQLITE_NOMEM] is returned if malloc() fails. ** [SQLITE_MISUSE] might be returned if these routines are called on a ** virtual machine that is the wrong state or which has already been finalized. ** Detection of misuse is unreliable. Applications should not depend ** on SQLITE_MISUSE returns. SQLITE_MISUSE is intended to indicate a ** a logic error in the application. Future versions of SQLite might ** panic rather than return SQLITE_MISUSE. ** ** See also: [sqlite3_bind_parameter_count()], ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** ** {F13506} The [SQL statement compiler] recognizes tokens of the forms ** "?", "?NNN", "$VVV", ":VVV", and "@VVV" as SQL parameters, ** where NNN is any sequence of one or more digits ** and where VVV is any sequence of one or more alphanumeric ** characters or "::" optionally followed by a string containing ** no spaces and contained within parentheses. ** ** {F13509} The initial value of an SQL parameter is NULL. ** ** {F13512} The index of an "?" SQL parameter is one larger than the ** largest index of SQL parameter to the left, or 1 if ** the "?" is the leftmost SQL parameter. ** ** {F13515} The index of an "?NNN" SQL parameter is the integer NNN. ** ** {F13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is ** the same as the index of leftmost occurrences of the same ** parameter, or one more than the largest index over all ** parameters to the left if this is the first occurrence ** of this parameter, or 1 if this is the leftmost parameter. ** ** {F13521} The [SQL statement compiler] fails with an [SQLITE_RANGE] ** error if the index of an SQL parameter is less than 1 ** or greater than the compile-time SQLITE_MAX_VARIABLE_NUMBER ** parameter. ** ** {F13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)] ** associate the value V with all SQL parameters having an ** index of N in the [prepared statement] S. ** ** {F13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)] ** override prior calls with the same values of S and N. ** ** {F13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)] ** persist across calls to [sqlite3_reset(S)]. ** ** {F13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L ** bytes of the BLOB or string pointed to by V, when L ** is non-negative. ** ** {F13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters ** from V through the first zero character when L is negative. ** ** {F13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special ** constant [SQLITE_STATIC], SQLite assumes that the value V ** is held in static unmanaged space that will not change ** during the lifetime of the binding. ** ** {F13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special ** constant [SQLITE_TRANSIENT], the routine makes a ** private copy of the value V before it returns. ** ** {F13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)], ** [sqlite3_bind_text(S,N,V,L,D)], or ** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to ** a function, SQLite invokes that function to destroy the ** value V after it has finished using the value V. ** ** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound ** is a BLOB of L bytes, or a zero-length BLOB if L is negative. ** ** {F13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may ** be either a [protected sqlite3_value] object or an ** [unprotected sqlite3_value] object. */ int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_double(sqlite3_stmt*, int, double); int sqlite3_bind_int(sqlite3_stmt*, int, int); int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); int sqlite3_bind_null(sqlite3_stmt*, int); int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); /* ** CAPI3REF: Number Of SQL Parameters {F13600} ** ** This routine can be used to find the number of [SQL parameters] ** in a [prepared statement]. SQL parameters are tokens of the ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as ** placeholders for values that are [sqlite3_bind_blob | bound] ** to the parameters at a later time. ** ** This routine actually returns the index of the largest (right-most) ** parameter. For all forms except ?NNN, this will correspond to the ** number of unique parameters. If parameters of the ?NNN are used, ** there may be gaps in the list. ** ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_name()], and ** [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** ** {F13601} The [sqlite3_bind_parameter_count(S)] interface returns ** the largest index of all SQL parameters in the ** [prepared statement] S, or 0 if S contains no SQL parameters. */ int sqlite3_bind_parameter_count(sqlite3_stmt*); /* ** CAPI3REF: Name Of A Host Parameter {F13620} ** ** This routine returns a pointer to the name of the n-th ** [SQL parameter] in a [prepared statement]. ** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA" ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA" ** respectively. ** In other words, the initial ":" or "$" or "@" or "?" ** is included as part of the name. ** Parameters of the form "?" without a following integer have no name ** and are also referred to as "anonymous parameters". ** ** The first host parameter has an index of 1, not 0. ** ** If the value n is out of range or if the n-th parameter is ** nameless, then NULL is returned. The returned string is ** always in UTF-8 encoding even if the named parameter was ** originally specified as UTF-16 in [sqlite3_prepare16()] or ** [sqlite3_prepare16_v2()]. ** ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_count()], and ** [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** ** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns ** a UTF-8 rendering of the name of the SQL parameter in ** the [prepared statement] S having index N, or ** NULL if there is no SQL parameter with index N or if the ** parameter with index N is an anonymous parameter "?". */ const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int); /* ** CAPI3REF: Index Of A Parameter With A Given Name {F13640} |
︙ | ︙ | |||
3007 3008 3009 3010 3011 3012 3013 | ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_count()], and ** [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** ** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns | | | | < | | | < | | | < | | < | | | | < | | | < | | < | | | | | | | 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 | ** See also: [sqlite3_bind_blob|sqlite3_bind()], ** [sqlite3_bind_parameter_count()], and ** [sqlite3_bind_parameter_index()]. ** ** INVARIANTS: ** ** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns ** the index of SQL parameter in the [prepared statement] ** S whose name matches the UTF-8 string N, or 0 if there is ** no match. */ int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName); /* ** CAPI3REF: Reset All Bindings On A Prepared Statement {F13660} ** ** Contrary to the intuition of many, [sqlite3_reset()] does not reset ** the [sqlite3_bind_blob | bindings] on a [prepared statement]. ** Use this routine to reset all host parameters to NULL. ** ** INVARIANTS: ** ** {F13661} The [sqlite3_clear_bindings(S)] interface resets all SQL ** parameter bindings in the [prepared statement] S back to NULL. */ int sqlite3_clear_bindings(sqlite3_stmt*); /* ** CAPI3REF: Number Of Columns In A Result Set {F13710} ** ** Return the number of columns in the result set returned by the ** [prepared statement]. This routine returns 0 if pStmt is an SQL ** statement that does not return data (for example an UPDATE). ** ** INVARIANTS: ** ** {F13711} The [sqlite3_column_count(S)] interface returns the number of ** columns in the result set generated by the [prepared statement] S, ** or 0 if S does not generate a result set. */ int sqlite3_column_count(sqlite3_stmt *pStmt); /* ** CAPI3REF: Column Names In A Result Set {F13720} ** ** These routines return the name assigned to a particular column ** in the result set of a SELECT statement. The sqlite3_column_name() ** interface returns a pointer to a zero-terminated UTF-8 string ** and sqlite3_column_name16() returns a pointer to a zero-terminated ** UTF-16 string. The first parameter is the [prepared statement] ** that implements the SELECT statement. The second parameter is the ** column number. The leftmost column is number 0. ** ** The returned string pointer is valid until either the [prepared statement] ** is destroyed by [sqlite3_finalize()] or until the next call to ** sqlite3_column_name() or sqlite3_column_name16() on the same column. ** ** If sqlite3_malloc() fails during the processing of either routine ** (for example during a conversion from UTF-8 to UTF-16) then a ** NULL pointer is returned. ** ** The name of a result column is the value of the "AS" clause for ** that column, if there is an AS clause. If there is no AS clause ** then the name of the column is unspecified and may change from ** one release of SQLite to the next. ** ** INVARIANTS: ** ** {F13721} A successful invocation of the [sqlite3_column_name(S,N)] ** interface returns the name of the Nth column (where 0 is ** the leftmost column) for the result set of the ** [prepared statement] S as a zero-terminated UTF-8 string. ** ** {F13723} A successful invocation of the [sqlite3_column_name16(S,N)] ** interface returns the name of the Nth column (where 0 is ** the leftmost column) for the result set of the ** [prepared statement] S as a zero-terminated UTF-16 string ** in the native byte order. ** ** {F13724} The [sqlite3_column_name()] and [sqlite3_column_name16()] ** interfaces return a NULL pointer if they are unable to ** allocate memory to hold their normal return strings. ** ** {F13725} If the N parameter to [sqlite3_column_name(S,N)] or ** [sqlite3_column_name16(S,N)] is out of range, then the ** interfaces return a NULL pointer. ** ** {F13726} The strings returned by [sqlite3_column_name(S,N)] and ** [sqlite3_column_name16(S,N)] are valid until the next ** call to either routine with the same S and N parameters ** or until [sqlite3_finalize(S)] is called. ** ** {F13727} When a result column of a [SELECT] statement contains ** an AS clause, the name of that column is the identifier |
︙ | ︙ | |||
3700 3701 3702 3703 3704 3705 3706 | ** {F11338} The [sqlite3_reset(S)] interface does not change the values ** of any [sqlite3_bind_blob|bindings] on [prepared statement] S. */ int sqlite3_reset(sqlite3_stmt *pStmt); /* ** CAPI3REF: Create Or Redefine SQL Functions {F16100} | | > > | 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 | ** {F11338} The [sqlite3_reset(S)] interface does not change the values ** of any [sqlite3_bind_blob|bindings] on [prepared statement] S. */ int sqlite3_reset(sqlite3_stmt *pStmt); /* ** CAPI3REF: Create Or Redefine SQL Functions {F16100} ** KEYWORDS: {function creation routines} ** KEYWORDS: {application-defined SQL function} ** KEYWORDS: {application-defined SQL functions} ** ** 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(). |
︙ | ︙ | |||
4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 4883 4884 | sqlite3*, void(*)(void *,int ,char const *,char const *,sqlite3_int64), void* ); /* ** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330} ** ** This routine enables or disables the sharing of the database cache ** and schema data structures between connections to the same database. ** Sharing is enabled if the argument is true and disabled if the argument ** is false. ** ** Cache sharing is enabled and disabled | > | 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 | sqlite3*, void(*)(void *,int ,char const *,char const *,sqlite3_int64), void* ); /* ** CAPI3REF: Enable Or Disable Shared Pager Cache {F10330} ** KEYWORDS: {shared cache} {shared cache mode} ** ** This routine enables or disables the sharing of the database cache ** and schema data structures between connections to the same database. ** Sharing is enabled if the argument is true and disabled if the argument ** is false. ** ** Cache sharing is enabled and disabled |
︙ | ︙ | |||
5427 5428 5429 5430 5431 5432 5433 | ****** EXPERIMENTAL - subject to change without notice ************** */ /* ** CAPI3REF: A Handle To An Open BLOB {F17800} ** ** An instance of this object represents an open BLOB on which | | | 5402 5403 5404 5405 5406 5407 5408 5409 5410 5411 5412 5413 5414 5415 5416 | ****** EXPERIMENTAL - subject to change without notice ************** */ /* ** CAPI3REF: A Handle To An Open BLOB {F17800} ** ** An instance of this object represents an open BLOB on which ** [sqlite3_blob_open | incremental BLOB I/O] can be preformed. ** Objects of this type are created by ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()]. ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces ** can be used to read or write small subsections of the blob. ** The [sqlite3_blob_bytes()] interface returns the size of the ** blob in bytes. */ |
︙ | ︙ |