/ Check-in [54f1df7b]
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Reworking the documentation on integer result codes. This is a comment and documentation change only. There are no changes to code.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 54f1df7b63166f14b2f0d5955c546820e5cbdec9
User & Date: drh 2014-08-08 12:51:42
Context
2014-08-08
15:38
The SQLITE_IOERR_BLOCKED extended error code is not longer used, so remove assert() statements and documentation for that error code. Also make other documentation improvements. check-in: 36b7c5ce user: drh tags: trunk
12:51
Reworking the documentation on integer result codes. This is a comment and documentation change only. There are no changes to code. check-in: 54f1df7b user: drh tags: trunk
2014-08-07
20:42
When the estimated sorting cost overwhelms the estimated lookup cost, ensure that lookup costs are still taken into account when selecting a lookup algorithm. check-in: 2af630c5 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

   260    260   #endif
   261    261   
   262    262   /*
   263    263   ** CAPI3REF: Closing A Database Connection
   264    264   **
   265    265   ** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
   266    266   ** for the [sqlite3] object.
   267         -** ^Calls to sqlite3_close() and sqlite3_close_v2() return SQLITE_OK if
          267  +** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
   268    268   ** the [sqlite3] object is successfully destroyed and all associated
   269    269   ** resources are deallocated.
   270    270   **
   271    271   ** ^If the database connection is associated with unfinalized prepared
   272    272   ** statements or unfinished sqlite3_backup objects then sqlite3_close()
   273    273   ** will leave the database connection open and return [SQLITE_BUSY].
   274    274   ** ^If sqlite3_close_v2() is called with unfinalized prepared statements
................................................................................
   281    281   **
   282    282   ** Applications should [sqlite3_finalize | finalize] all [prepared statements],
   283    283   ** [sqlite3_blob_close | close] all [BLOB handles], and 
   284    284   ** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
   285    285   ** with the [sqlite3] object prior to attempting to close the object.  ^If
   286    286   ** sqlite3_close_v2() is called on a [database connection] that still has
   287    287   ** outstanding [prepared statements], [BLOB handles], and/or
   288         -** [sqlite3_backup] objects then it returns SQLITE_OK but the deallocation
          288  +** [sqlite3_backup] objects then it returns [SQLITE_OK] but the deallocation
   289    289   ** of resources is deferred until all [prepared statements], [BLOB handles],
   290    290   ** and [sqlite3_backup] objects are also destroyed.
   291    291   **
   292    292   ** ^If an [sqlite3] object is destroyed while a transaction is open,
   293    293   ** the transaction is automatically rolled back.
   294    294   **
   295    295   ** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
................................................................................
   377    377     int (*callback)(void*,int,char**,char**),  /* Callback function */
   378    378     void *,                                    /* 1st argument to callback */
   379    379     char **errmsg                              /* Error msg written here */
   380    380   );
   381    381   
   382    382   /*
   383    383   ** CAPI3REF: Result Codes
   384         -** KEYWORDS: SQLITE_OK {error code} {error codes}
   385         -** KEYWORDS: {result code} {result codes}
          384  +** KEYWORDS: {result code definitions}
   386    385   **
   387    386   ** Many SQLite functions return an integer result code from the set shown
   388    387   ** here in order to indicate success or failure.
   389    388   **
   390    389   ** New error codes may be added in future versions of SQLite.
   391    390   **
   392         -** See also: [SQLITE_IOERR_READ | extended result codes],
   393         -** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes].
          391  +** See also: [extended result code definitions]
   394    392   */
   395    393   #define SQLITE_OK           0   /* Successful result */
   396    394   /* beginning-of-error-codes */
   397    395   #define SQLITE_ERROR        1   /* SQL error or missing database */
   398    396   #define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
   399    397   #define SQLITE_PERM         3   /* Access permission denied */
   400    398   #define SQLITE_ABORT        4   /* Callback routine requested an abort */
................................................................................
   424    422   #define SQLITE_WARNING     28   /* Warnings from sqlite3_log() */
   425    423   #define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
   426    424   #define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
   427    425   /* end-of-error-codes */
   428    426   
   429    427   /*
   430    428   ** CAPI3REF: Extended Result Codes
   431         -** KEYWORDS: {extended error code} {extended error codes}
   432         -** KEYWORDS: {extended result code} {extended result codes}
          429  +** KEYWORDS: {extended result code definitions}
   433    430   **
   434         -** In its default configuration, SQLite API routines return one of 26 integer
   435         -** [SQLITE_OK | result codes].  However, experience has shown that many of
          431  +** In its default configuration, SQLite API routines return one of 30 integer
          432  +** [result codes].  However, experience has shown that many of
   436    433   ** these result codes are too coarse-grained.  They do not provide as
   437    434   ** much information about problems as programmers might like.  In an effort to
   438    435   ** address this, newer versions of SQLite (version 3.3.8 and later) include
   439    436   ** support for additional result codes that provide more detailed information
   440         -** about errors. The extended result codes are enabled or disabled
          437  +** about errors. These [extended result codes] are enabled or disabled
   441    438   ** on a per database connection basis using the
   442         -** [sqlite3_extended_result_codes()] API.
   443         -**
   444         -** Some of the available extended result codes are listed here.
   445         -** One may expect the number of extended result codes will increase
   446         -** over time.  Software that uses extended result codes should expect
   447         -** to see new result codes in future releases of SQLite.
   448         -**
   449         -** The SQLITE_OK result code will never be extended.  It will always
   450         -** be exactly zero.
          439  +** [sqlite3_extended_result_codes()] API.  Or, the extended code for
          440  +** the most recent error can be obtained using
          441  +** [sqlite3_extended_errcode()].
   451    442   */
   452    443   #define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
   453    444   #define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
   454    445   #define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
   455    446   #define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
   456    447   #define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
   457    448   #define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
................................................................................
  2519   2510   **
  2520   2511   ** The [sqlite3_set_authorizer | authorizer callback function] must
  2521   2512   ** return either [SQLITE_OK] or one of these two constants in order
  2522   2513   ** to signal SQLite whether or not the action is permitted.  See the
  2523   2514   ** [sqlite3_set_authorizer | authorizer documentation] for additional
  2524   2515   ** information.
  2525   2516   **
  2526         -** Note that SQLITE_IGNORE is also used as a [SQLITE_ROLLBACK | return code]
  2527         -** from the [sqlite3_vtab_on_conflict()] interface.
         2517  +** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
         2518  +** returned from the [sqlite3_vtab_on_conflict()] interface.
  2528   2519   */
  2529   2520   #define SQLITE_DENY   1   /* Abort the SQL statement with an error */
  2530   2521   #define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
  2531   2522   
  2532   2523   /*
  2533   2524   ** CAPI3REF: Authorizer Action Codes
  2534   2525   **
................................................................................
  7360   7351   ** of the SQL statement that triggered the call to the [xUpdate] method of the
  7361   7352   ** [virtual table].
  7362   7353   */
  7363   7354   int sqlite3_vtab_on_conflict(sqlite3 *);
  7364   7355   
  7365   7356   /*
  7366   7357   ** CAPI3REF: Conflict resolution modes
         7358  +** KEYWORDS: {conflict resolution mode}
  7367   7359   **
  7368   7360   ** These constants are returned by [sqlite3_vtab_on_conflict()] to
  7369   7361   ** inform a [virtual table] implementation what the [ON CONFLICT] mode
  7370   7362   ** is for the SQL statement being evaluated.
  7371   7363   **
  7372   7364   ** Note that the [SQLITE_IGNORE] constant is also used as a potential
  7373   7365   ** return value from the [sqlite3_set_authorizer()] callback and that