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

Changes to src/sqlite.h.in.

  1515   1515   ** This option can be used to overload the default memory allocation
  1516   1516   ** routines with a wrapper that simulations memory allocation failure or
  1517   1517   ** tracks memory usage, for example. </dd>
  1518   1518   **
  1519   1519   ** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
  1520   1520   ** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
  1521   1521   ** interpreted as a boolean, which enables or disables the collection of
  1522         -** memory allocation statistics. ^(When memory allocation statistics are disabled, the 
  1523         -** following SQLite interfaces become non-operational:
         1522  +** memory allocation statistics. ^(When memory allocation statistics are
         1523  +** disabled, the following SQLite interfaces become non-operational:
  1524   1524   **   <ul>
  1525   1525   **   <li> [sqlite3_memory_used()]
  1526   1526   **   <li> [sqlite3_memory_highwater()]
  1527   1527   **   <li> [sqlite3_soft_heap_limit64()]
  1528   1528   **   <li> [sqlite3_status()]
  1529   1529   **   </ul>)^
  1530   1530   ** ^Memory allocation statistics are enabled by default unless SQLite is
................................................................................
  1557   1557   ** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
  1558   1558   ** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a static memory buffer
  1559   1559   ** that SQLite can use for the database page cache with the default page
  1560   1560   ** cache implementation.  
  1561   1561   ** This configuration should not be used if an application-define page
  1562   1562   ** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2]
  1563   1563   ** configuration option.
  1564         -** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to 8-byte aligned
         1564  +** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
         1565  +** 8-byte aligned
  1565   1566   ** memory, the size of each page buffer (sz), and the number of pages (N).
  1566   1567   ** The sz argument should be the size of the largest database page
  1567   1568   ** (a power of two between 512 and 32768) plus some extra bytes for each
  1568   1569   ** page header.  ^The number of extra bytes needed by the page header
  1569   1570   ** can be determined using the [SQLITE_CONFIG_PCACHE_HDRSZ] option 
  1570   1571   ** to [sqlite3_config()].
  1571   1572   ** ^It is harmless, apart from the wasted memory,
................................................................................
  1577   1578   ** memory needs for the first N pages that it adds to cache.  ^If additional
  1578   1579   ** page cache memory is needed beyond what is provided by this option, then
  1579   1580   ** SQLite goes to [sqlite3_malloc()] for the additional storage space.</dd>
  1580   1581   **
  1581   1582   ** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
  1582   1583   ** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer 
  1583   1584   ** that SQLite will use for all of its dynamic memory allocation needs
  1584         -** beyond those provided for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
         1585  +** beyond those provided for by [SQLITE_CONFIG_SCRATCH] and
         1586  +** [SQLITE_CONFIG_PAGECACHE].
  1585   1587   ** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
  1586   1588   ** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
  1587   1589   ** [SQLITE_ERROR] if invoked otherwise.
  1588   1590   ** ^There are three arguments to SQLITE_CONFIG_HEAP:
  1589   1591   ** An 8-byte aligned pointer to the memory,
  1590   1592   ** the number of bytes in the memory buffer, and the minimum allocation size.
  1591   1593   ** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
................................................................................
  1597   1599   ** boundary or subsequent behavior of SQLite will be undefined.
  1598   1600   ** The minimum allocation size is capped at 2**12. Reasonable values
  1599   1601   ** for the minimum allocation size are 2**5 through 2**8.</dd>
  1600   1602   **
  1601   1603   ** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
  1602   1604   ** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
  1603   1605   ** pointer to an instance of the [sqlite3_mutex_methods] structure.
  1604         -** The argument specifies alternative low-level mutex routines to be used in place
  1605         -** the mutex routines built into SQLite.)^  ^SQLite makes a copy of the
  1606         -** content of the [sqlite3_mutex_methods] structure before the call to
         1606  +** The argument specifies alternative low-level mutex routines to be used
         1607  +** in place the mutex routines built into SQLite.)^  ^SQLite makes a copy of
         1608  +** the content of the [sqlite3_mutex_methods] structure before the call to
  1607   1609   ** [sqlite3_config()] returns. ^If SQLite is compiled with
  1608   1610   ** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
  1609   1611   ** the entire mutexing subsystem is omitted from the build and hence calls to
  1610   1612   ** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
  1611   1613   ** return [SQLITE_ERROR].</dd>
  1612   1614   **
  1613   1615   ** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
................................................................................
  1637   1639   ** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is 
  1638   1640   ** a pointer to an [sqlite3_pcache_methods2] object.  This object specifies
  1639   1641   ** the interface to a custom page cache implementation.)^
  1640   1642   ** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
  1641   1643   **
  1642   1644   ** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
  1643   1645   ** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
  1644         -** is a pointer to an [sqlite3_pcache_methods2] object.  SQLite copies of the current
  1645         -** page cache implementation into that object.)^ </dd>
         1646  +** is a pointer to an [sqlite3_pcache_methods2] object.  SQLite copies of
         1647  +** the current page cache implementation into that object.)^ </dd>
  1646   1648   **
  1647   1649   ** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
  1648   1650   ** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
  1649   1651   ** global [error log].
  1650   1652   ** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
  1651   1653   ** function with a call signature of void(*)(void*,int,const char*), 
  1652   1654   ** and a pointer to void. ^If the function pointer is not NULL, it is
................................................................................
  1663   1665   ** supplied by the application must not invoke any SQLite interface.
  1664   1666   ** In a multi-threaded application, the application-defined logger
  1665   1667   ** function must be threadsafe. </dd>
  1666   1668   **
  1667   1669   ** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
  1668   1670   ** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
  1669   1671   ** If non-zero, then URI handling is globally enabled. If the parameter is zero,
  1670         -** then URI handling is globally disabled.)^ ^If URI handling is globally enabled,
  1671         -** all filenames passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or
         1672  +** then URI handling is globally disabled.)^ ^If URI handling is globally
         1673  +** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
         1674  +** [sqlite3_open16()] or
  1672   1675   ** specified as part of [ATTACH] commands are interpreted as URIs, regardless
  1673   1676   ** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
  1674   1677   ** connection is opened. ^If it is globally disabled, filenames are
  1675   1678   ** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
  1676   1679   ** database connection is opened. ^(By default, URI handling is globally
  1677   1680   ** disabled. The default value may be changed by compiling with the
  1678   1681   ** [SQLITE_USE_URI] symbol defined.)^
................................................................................
  1726   1729   ** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
  1727   1730   ** ^If either argument to this option is negative, then that argument is
  1728   1731   ** changed to its compile-time default.
  1729   1732   **
  1730   1733   ** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
  1731   1734   ** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
  1732   1735   ** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
  1733         -** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro defined.
  1734         -** ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
         1736  +** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
         1737  +** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
  1735   1738   ** that specifies the maximum size of the created heap.
  1736   1739   ** </dl>
  1737   1740   **
  1738   1741   ** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
  1739   1742   ** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
  1740   1743   ** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
  1741   1744   ** is a pointer to an integer and writes into that integer the number of extra
  1742         -** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE]. The amount of
  1743         -** extra space required can change depending on the compiler,
         1745  +** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
         1746  +** The amount of extra space required can change depending on the compiler,
  1744   1747   ** target platform, and SQLite version.
  1745   1748   ** </dl>
  1746   1749   */
  1747   1750   #define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
  1748   1751   #define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
  1749   1752   #define SQLITE_CONFIG_SERIALIZED    3  /* nil */
  1750   1753   #define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
................................................................................
  2040   2043   ** UTF-16 string in native byte order.
  2041   2044   */
  2042   2045   int sqlite3_complete(const char *sql);
  2043   2046   int sqlite3_complete16(const void *sql);
  2044   2047   
  2045   2048   /*
  2046   2049   ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
         2050  +** KEYWORDS: {busy-handler callback} {busy handler}
  2047   2051   **
  2048   2052   ** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
  2049   2053   ** that might be invoked with argument P whenever
  2050   2054   ** an attempt is made to access a database table associated with
  2051   2055   ** [database connection] D when another thread
  2052   2056   ** or process has the table locked.
  2053   2057   ** The sqlite3_busy_handler() interface is used to implement
................................................................................
  4511   4515   ** kind of [sqlite3_value] object can be used with this interface.
  4512   4516   **
  4513   4517   ** If these routines are called from within the different thread
  4514   4518   ** than the one containing the application-defined function that received
  4515   4519   ** the [sqlite3_context] pointer, the results are undefined.
  4516   4520   */
  4517   4521   void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
  4518         -void sqlite3_result_blob64(sqlite3_context*,const void*,sqlite3_uint64,void(*)(void*));
         4522  +void sqlite3_result_blob64(sqlite3_context*,const void*,
         4523  +                           sqlite3_uint64,void(*)(void*));
  4519   4524   void sqlite3_result_double(sqlite3_context*, double);
  4520   4525   void sqlite3_result_error(sqlite3_context*, const char*, int);
  4521   4526   void sqlite3_result_error16(sqlite3_context*, const void*, int);
  4522   4527   void sqlite3_result_error_toobig(sqlite3_context*);
  4523   4528   void sqlite3_result_error_nomem(sqlite3_context*);
  4524   4529   void sqlite3_result_error_code(sqlite3_context*, int);
  4525   4530   void sqlite3_result_int(sqlite3_context*, int);
................................................................................
  7258   7263   ** complication) of [sqlite3_wal_checkpoint_v2()].
  7259   7264   */
  7260   7265   int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);
  7261   7266   
  7262   7267   /*
  7263   7268   ** CAPI3REF: Checkpoint a database
  7264   7269   **
  7265         -** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint operation
  7266         -** on database X of [database connection] D in mode M.  Status information is
  7267         -** written back into integers pointed to by L and C.)^  ^(The M parameter must be
  7268         -** a valid [SQLITE_CHECKPOINT_PASSIVE|checkpoint mode]:)^
         7270  +** ^(The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
         7271  +** operation on database X of [database connection] D in mode M.  Status
         7272  +** information is written back into integers pointed to by L and C.)^
         7273  +** ^(The M parameter must be a valid [checkpoint mode]:)^
  7269   7274   **
  7270   7275   ** <dl>
  7271   7276   ** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
  7272   7277   **   ^Checkpoint as many frames as possible without waiting for any database 
  7273   7278   **   readers or writers to finish, then sync the database file if all frames 
  7274         -**   in the log were checkpointed. ^The [sqlite3_busy_handler|busy-handler callback]
  7275         -**   is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.  ^On the other hand,
  7276         -**   passive mode might leave the checkpoint unfinished if there are concurrent
  7277         -**   readers or writers.
         7279  +**   in the log were checkpointed. ^The [busy-handler callback]
         7280  +**   is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.  
         7281  +**   ^On the other hand, passive mode might leave the checkpoint unfinished
         7282  +**   if there are concurrent readers or writers.
  7278   7283   **
  7279   7284   ** <dt>SQLITE_CHECKPOINT_FULL<dd>
  7280   7285   **   ^This mode blocks (it invokes the
  7281   7286   **   [sqlite3_busy_handler|busy-handler callback]) until there is no
  7282   7287   **   database writer and all readers are reading from the most recent database
  7283   7288   **   snapshot. ^It then checkpoints all frames in the log file and syncs the
  7284   7289   **   database file. ^This mode blocks new database writers while it is pending,
  7285   7290   **   but new database readers are allowed to continue unimpeded.
  7286   7291   **
  7287   7292   ** <dt>SQLITE_CHECKPOINT_RESTART<dd>
  7288   7293   **   ^This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
  7289   7294   **   that after checkpointing the log file it blocks (calls the 
  7290         -**   [sqlite3_busy_handler|busy-handler callback])
         7295  +**   [busy-handler callback])
  7291   7296   **   until all readers are reading from the database file only. ^This ensures 
  7292   7297   **   that the next writer will restart the log file from the beginning.
  7293   7298   **   ^Like SQLITE_CHECKPOINT_FULL, this mode blocks new
  7294   7299   **   database writer attempts while it is pending, but does not impede readers.
  7295   7300   **
  7296   7301   ** <dt>SQLITE_CHECKPOINT_TRUNCATE<dd>
  7297         -**   ^This mode works the same way as SQLITE_CHECKPOINT_RESTART with the addition
  7298         -**   that it also truncates the log file to zero bytes just prior to a successful
  7299         -**   return.
         7302  +**   ^This mode works the same way as SQLITE_CHECKPOINT_RESTART with the
         7303  +**   addition that it also truncates the log file to zero bytes just prior
         7304  +**   to a successful return.
  7300   7305   ** </dl>
  7301   7306   **
  7302   7307   ** ^If pnLog is not NULL, then *pnLog is set to the total number of frames in
  7303   7308   ** the log file or to -1 if the checkpoint could not run because
  7304         -** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not NULL,
  7305         -** then *pnCkpt is set to the total number of checkpointed frames in the log file
  7306         -** (including any that were already checkpointed before the function was called)
  7307         -** or to -1 if the checkpoint could not run due to an error or because the
  7308         -** database is not in WAL mode. ^Note that upon successful completion of
  7309         -** an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been truncated to
  7310         -** zero bytes and so both *pnLog and *pnCkpt will be set to zero.
         7309  +** of an error or because the database is not in [WAL mode]. ^If pnCkpt is not
         7310  +** NULL,then *pnCkpt is set to the total number of checkpointed frames in the
         7311  +** log file (including any that were already checkpointed before the function
         7312  +** was called) or to -1 if the checkpoint could not run due to an error or
         7313  +** because the database is not in WAL mode. ^Note that upon successful
         7314  +** completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been
         7315  +** truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.
  7311   7316   **
  7312   7317   ** ^All calls obtain an exclusive "checkpoint" lock on the database file. ^If
  7313   7318   ** any other process is running a checkpoint operation at the same time, the 
  7314   7319   ** lock cannot be obtained and SQLITE_BUSY is returned. ^Even if there is a 
  7315   7320   ** busy-handler configured, it will not be invoked in this case.
  7316   7321   **
  7317   7322   ** ^The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the 
................................................................................
  7363   7368   ** KEYWORDS: {checkpoint mode}
  7364   7369   **
  7365   7370   ** These constants define all valid values for the "checkpoint mode" passed
  7366   7371   ** as the third parameter to the [sqlite3_wal_checkpoint_v2()] interface.
  7367   7372   ** See the [sqlite3_wal_checkpoint_v2()] documentation for details on the
  7368   7373   ** meaning of each of these checkpoint modes.
  7369   7374   */
  7370         -#define SQLITE_CHECKPOINT_PASSIVE  0  /* Do as much as possible without blocking */
  7371         -#define SQLITE_CHECKPOINT_FULL     1  /* Wait for writers to finish, then checkpoint */
  7372         -#define SQLITE_CHECKPOINT_RESTART  2  /* Like FULL but afterwards block for readers */
  7373         -#define SQLITE_CHECKPOINT_TRUNCATE 3  /* Like RESTART but also truncate the WAL file */
         7375  +#define SQLITE_CHECKPOINT_PASSIVE  0  /* Do as much as possible w/o blocking */
         7376  +#define SQLITE_CHECKPOINT_FULL     1  /* Wait for writers, then checkpoint */
         7377  +#define SQLITE_CHECKPOINT_RESTART  2  /* Like FULL but wait for for readers */
         7378  +#define SQLITE_CHECKPOINT_TRUNCATE 3  /* Like RESTART but also truncate WAL */
  7374   7379   
  7375   7380   /*
  7376   7381   ** CAPI3REF: Virtual Table Interface Configuration
  7377   7382   **
  7378   7383   ** This function may be called by either the [xConnect] or [xCreate] method
  7379   7384   ** of a [virtual table] implementation to configure
  7380   7385   ** various facets of the virtual table interface.
................................................................................
  7465   7470   **
  7466   7471   ** The following constants can be used for the T parameter to the
  7467   7472   ** [sqlite3_stmt_scanstatus(S,X,T,V)] interface.  Each constant designates a
  7468   7473   ** different metric for sqlite3_stmt_scanstatus() to return.
  7469   7474   **
  7470   7475   ** <dl>
  7471   7476   ** [[SQLITE_SCANSTAT_NLOOP]] <dt>SQLITE_SCANSTAT_NLOOP</dt>
  7472         -** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set to the
  7473         -** total number of times that the X-th loop has run.</dd>
         7477  +** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be
         7478  +** set to the total number of times that the X-th loop has run.</dd>
  7474   7479   **
  7475   7480   ** [[SQLITE_SCANSTAT_NVISIT]] <dt>SQLITE_SCANSTAT_NVISIT</dt>
  7476         -** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set to the
  7477         -** total number of rows examined by all iterations of the X-th loop.</dd>
         7481  +** <dd>^The [sqlite3_int64] variable pointed to by the T parameter will be set
         7482  +** to the total number of rows examined by all iterations of the X-th loop.</dd>
  7478   7483   **
  7479   7484   ** [[SQLITE_SCANSTAT_EST]] <dt>SQLITE_SCANSTAT_EST</dt>
  7480   7485   ** <dd>^The "double" variable pointed to by the T parameter will be set to the
  7481   7486   ** query planner's estimate for the average number of rows output from each
  7482   7487   ** iteration of the X-th loop.  If the query planner's estimates was accurate,
  7483   7488   ** then this value will approximate the quotient NVISIT/NLOOP and the
  7484   7489   ** product of this value for all prior loops with the same SELECTID will
  7485   7490   ** be the NLOOP value for the current loop.
  7486   7491   **
  7487   7492   ** [[SQLITE_SCANSTAT_NAME]] <dt>SQLITE_SCANSTAT_NAME</dt>
  7488         -** <dd>^The "const char *" variable pointed to by the T parameter will be set to 
  7489         -** a zero-terminated UTF-8 string containing the name of the index or table used
  7490         -** for the X-th loop.
         7493  +** <dd>^The "const char *" variable pointed to by the T parameter will be set
         7494  +** to a zero-terminated UTF-8 string containing the name of the index or table
         7495  +** used for the X-th loop.
  7491   7496   **
  7492   7497   ** [[SQLITE_SCANSTAT_EXPLAIN]] <dt>SQLITE_SCANSTAT_EXPLAIN</dt>
  7493         -** <dd>^The "const char *" variable pointed to by the T parameter will be set to 
  7494         -** a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN] description
  7495         -** for the X-th loop.
         7498  +** <dd>^The "const char *" variable pointed to by the T parameter will be set
         7499  +** to a zero-terminated UTF-8 string containing the [EXPLAIN QUERY PLAN]
         7500  +** description for the X-th loop.
  7496   7501   **
  7497   7502   ** [[SQLITE_SCANSTAT_SELECTID]] <dt>SQLITE_SCANSTAT_SELECT</dt>
  7498   7503   ** <dd>^The "int" variable pointed to by the T parameter will be set to the
  7499   7504   ** "select-id" for the X-th loop.  The select-id identifies which query or
  7500   7505   ** subquery the loop is part of.  The main query has a select-id of zero.
  7501   7506   ** The select-id is the same value as is output in the first column
  7502   7507   ** of an [EXPLAIN QUERY PLAN] query.
................................................................................
  7511   7516   
  7512   7517   /*
  7513   7518   ** CAPI3REF: Prepared Statement Scan Status
  7514   7519   **
  7515   7520   ** Return status data for a single loop within query pStmt.
  7516   7521   **
  7517   7522   ** The "iScanStatusOp" parameter determines which status information to return.
  7518         -** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior of
  7519         -** this interface is undefined.
         7523  +** The "iScanStatusOp" must be one of the [scanstatus options] or the behavior
         7524  +** of this interface is undefined.
  7520   7525   ** ^The requested measurement is written into a variable pointed to by
  7521   7526   ** the "pOut" parameter.
  7522   7527   ** Parameter "idx" identifies the specific loop to retrieve statistics for.
  7523   7528   ** Loops are numbered starting from zero. ^If idx is out of range - less than
  7524   7529   ** zero or greater than or equal to the total number of loops used to implement
  7525   7530   ** the statement - a non-zero value is returned and the variable that pOut
  7526   7531   ** points to is unchanged.