/ Check-in [ebd388e9]
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:Add requirements marks to the sqlite3_trace_v2() interface documentation.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | sqlite3_trace_v2
Files: files | file ages | folders
SHA1: ebd388e94da4a2b29c2a546f832d359619803ec5
User & Date: drh 2016-07-23 02:07:26
Context
2016-07-23
04:58
Improvements to sqlite3_trace_v2() documentation. Fix the sqlite3VdbeExpandSql() routine to respond better to OOM conditions. Closed-Leaf check-in: 0400f642 user: drh tags: sqlite3_trace_v2
02:07
Add requirements marks to the sqlite3_trace_v2() interface documentation. check-in: ebd388e9 user: drh tags: sqlite3_trace_v2
00:43
Fix sqlite3VdbeExpandSql() so that it handles OOMs by always returning NULL. check-in: 5a027fe4 user: drh tags: sqlite3_trace_v2
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  2791   2791   /*
  2792   2792   ** CAPI3REF: SQL Trace Event Codes
  2793   2793   ** KEYWORDS: SQLITE_TRACE
  2794   2794   **
  2795   2795   ** These constants identify classes of events that can be monitored
  2796   2796   ** using the [sqlite3_trace_v2()] tracing logic.  The third argument
  2797   2797   ** to [sqlite3_trace_v2()] is an OR-ed combination of one or more of
  2798         -** the following constants.  The first argument to the trace callback
         2798  +** the following constants.  ^The first argument to the trace callback
  2799   2799   ** is one of the following constants.
  2800   2800   **
  2801   2801   ** New tracing constants may be added in future releases.
  2802   2802   **
  2803         -** A trace callback has four arguments: xCallback(T,C,P,X).
  2804         -** The T argument is one of the integer type codes above.
  2805         -** The C argument is a copy of the context pointer passed in as the
         2803  +** ^A trace callback has four arguments: xCallback(T,C,P,X).
         2804  +** ^The T argument is one of the integer type codes above.
         2805  +** ^The C argument is a copy of the context pointer passed in as the
  2806   2806   ** fourth argument to [sqlite3_trace_v2()].
  2807   2807   ** The P and X arguments are pointers whose meanings depend on T.
  2808   2808   **
  2809   2809   ** <dl>
  2810   2810   ** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
  2811         -** <dd>An SQLITE_TRACE_STMT callback is invoked when a prepared statement
         2811  +** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
  2812   2812   ** first begins running and possibly at other times during the
  2813   2813   ** execution of the prepared statement, such as at the start of each
  2814         -** trigger subprogram.  The P argument is a pointer to the
  2815         -** [prepared statement].  The X argument is a pointer to a string which
         2814  +** trigger subprogram. ^The P argument is a pointer to the
         2815  +** [prepared statement]. ^The X argument is a pointer to a string which
  2816   2816   ** is the expanded SQL text of the prepared statement or a comment that
  2817   2817   ** indicates the invocation of a trigger.
  2818   2818   **
  2819   2819   ** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
  2820         -** <dd>An SQLITE_TRACE_PROFILE callback provides approximately the same
         2820  +** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
  2821   2821   ** information as is provided by the [sqlite3_profile()] callback.
  2822         -** The P argument is a pointer to the [prepared statement] and the
  2823         -** X argument points to a 64-bit integer which is the estimated of
         2822  +** ^The P argument is a pointer to the [prepared statement] and the
         2823  +** ^X argument points to a 64-bit integer which is the estimated of
  2824   2824   ** the number of nanosecond that the prepared statement took to run.
  2825         -** The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
         2825  +** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
  2826   2826   **
  2827   2827   ** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
  2828         -** <dd>An SQLITE_TRACE_ROW callback is invoked whenever a prepared
         2828  +** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
  2829   2829   ** statement generates a single row of result.  
  2830         -** The P argument is a pointer to the [prepared statement] and the
         2830  +** ^The P argument is a pointer to the [prepared statement] and the
  2831   2831   ** X argument is unused.
  2832   2832   **
  2833   2833   ** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
  2834         -** <dd>An SQLITE_TRACE_CLOSE callback is invoked when a database
         2834  +** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
  2835   2835   ** connection closes.
  2836         -** The P argument is a pointer to the [database connection] object
         2836  +** ^The P argument is a pointer to the [database connection] object
  2837   2837   ** and the X argument is unused.
  2838   2838   ** </dl>
  2839   2839   */
  2840   2840   #define SQLITE_TRACE_STMT       0x01
  2841   2841   #define SQLITE_TRACE_PROFILE    0x02
  2842   2842   #define SQLITE_TRACE_ROW        0x04
  2843   2843   #define SQLITE_TRACE_CLOSE      0x08
  2844   2844   
  2845   2845   /*
  2846   2846   ** CAPI3REF: SQL Trace Hook
  2847   2847   ** METHOD: sqlite3
  2848   2848   **
  2849         -** The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
         2849  +** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
  2850   2850   ** function X against [database connection] D, using property mask M
  2851         -** and context pointer P.  If the X callback is
         2851  +** and context pointer P.  ^If the X callback is
  2852   2852   ** NULL or if the M mask is zero, then tracing is disabled.  The
  2853   2853   ** M argument must be one or more of the [SQLITE_TRACE]
  2854   2854   ** constants.
  2855   2855   **
  2856         -** Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides 
         2856  +** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides 
  2857   2857   ** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
  2858   2858   **
  2859         -** The X callback is invoked whenever any of the events identified by 
  2860         -** mask M occur.  The integer return value from the callback is currently
         2859  +** ^The X callback is invoked whenever any of the events identified by 
         2860  +** mask M occur.  ^The integer return value from the callback is currently
  2861   2861   ** ignored, though this may change in future releases.  Callback
  2862   2862   ** implementations should return zero to ensure future compatibility.
  2863   2863   **
  2864         -** A trace callback is invoked with four arguments: callback(T,C,P,X).
  2865         -** The T argument is one of the [SQLITE_TRACE]
         2864  +** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
         2865  +** ^The T argument is one of the [SQLITE_TRACE]
  2866   2866   ** constants to indicate why the callback was invoked.
  2867         -** The C argument is a copy of the context pointer.
         2867  +** ^The C argument is a copy of the context pointer.
  2868   2868   ** The P and X arguments are pointers whose meanings depend on T.
  2869   2869   **
  2870   2870   ** The sqlite3_trace_v2() interface is intended to replace the legacy
  2871   2871   ** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
  2872   2872   ** are deprecated.
  2873   2873   */
  2874   2874   int sqlite3_trace_v2(

Changes to src/vdbeapi.c.

  1607   1607       return 0;
  1608   1608     }
  1609   1609   #endif
  1610   1610     v = pVdbe->aCounter[op];
  1611   1611     if( resetFlag ) pVdbe->aCounter[op] = 0;
  1612   1612     return (int)v;
  1613   1613   }
         1614  +
         1615  +/*
         1616  +** Return the SQL associated with a prepared statement
         1617  +*/
         1618  +const char *sqlite3_sql(sqlite3_stmt *pStmt){
         1619  +  Vdbe *p = (Vdbe *)pStmt;
         1620  +  return p ? p->zSql : 0;
         1621  +}
         1622  +
         1623  +/*
         1624  +** Return the SQL associated with a prepared statement with
         1625  +** bound parameters expanded.  Space to hold the returned string is
         1626  +** obtained from sqlite3_malloc().  The caller is responsible for
         1627  +** freeing the returned string by passing it to sqlite3_free().
         1628  +**
         1629  +** The SQLITE_TRACE_SIZE_LIMIT puts an upper bound on the size of
         1630  +** expanded bound parameters.
         1631  +*/
         1632  +char *sqlite3_expanded_sql(sqlite3_stmt *pStmt){
         1633  +#ifdef SQLITE_OMIT_TRACE
         1634  +  return 0;
         1635  +#else
         1636  +  char *z = 0;
         1637  +  const char *zSql = sqlite3_sql(pStmt);
         1638  +  if( zSql ){
         1639  +    Vdbe *p = (Vdbe *)pStmt;
         1640  +    sqlite3_mutex_enter(p->db->mutex);
         1641  +    z = sqlite3VdbeExpandSql(p, zSql);
         1642  +    sqlite3_mutex_leave(p->db->mutex);
         1643  +  }
         1644  +  return z;
         1645  +#endif
         1646  +}
  1614   1647   
  1615   1648   #ifdef SQLITE_ENABLE_PREUPDATE_HOOK
  1616   1649   /*
  1617   1650   ** Allocate and populate an UnpackedRecord structure based on the serialized
  1618   1651   ** record in nKey/pKey. Return a pointer to the new UnpackedRecord structure
  1619   1652   ** if successful, or a NULL pointer if an OOM error is encountered.
  1620   1653   */

Changes to src/vdbeaux.c.

    60     60     if( !isPrepareV2 ) return;
    61     61   #endif
    62     62     assert( p->zSql==0 );
    63     63     p->zSql = sqlite3DbStrNDup(p->db, z, n);
    64     64     p->isPrepareV2 = (u8)isPrepareV2;
    65     65   }
    66     66   
    67         -/*
    68         -** Return the SQL associated with a prepared statement
    69         -*/
    70         -const char *sqlite3_sql(sqlite3_stmt *pStmt){
    71         -  Vdbe *p = (Vdbe *)pStmt;
    72         -  return p ? p->zSql : 0;
    73         -}
    74         -
    75         -/*
    76         -** Return the SQL associated with a prepared statement with
    77         -** bound parameters expanded.  Space to hold the returned string is
    78         -** obtained from sqlite3_malloc().  The caller is responsible for
    79         -** freeing the returned string by passing it to sqlite3_free().
    80         -**
    81         -** The SQLITE_TRACE_SIZE_LIMIT puts an upper bound on the size of
    82         -** expanded bound parameters.
    83         -*/
    84         -char *sqlite3_expanded_sql(sqlite3_stmt *pStmt){
    85         -#ifdef SQLITE_OMIT_TRACE
    86         -  return 0;
    87         -#else
    88         -  char *z = 0;
    89         -  const char *zSql = sqlite3_sql(pStmt);
    90         -  if( zSql ){
    91         -    Vdbe *p = (Vdbe *)pStmt;
    92         -    sqlite3_mutex_enter(p->db->mutex);
    93         -    z = sqlite3VdbeExpandSql(p, zSql);
    94         -    sqlite3_mutex_leave(p->db->mutex);
    95         -  }
    96         -  return z;
    97         -#endif
    98         -}
    99         -
   100     67   /*
   101     68   ** Swap all content between two VDBE structures.
   102     69   */
   103     70   void sqlite3VdbeSwap(Vdbe *pA, Vdbe *pB){
   104     71     Vdbe tmp, *pTmp;
   105     72     char *zTmp;
   106     73     assert( pA->db==pB->db );

Changes to src/vdbetrace.c.

   137    137         }else if( pVar->flags & MEM_Str ){
   138    138           int nOut;  /* Number of bytes of the string text to include in output */
   139    139   #ifndef SQLITE_OMIT_UTF16
   140    140           u8 enc = ENC(db);
   141    141           if( enc!=SQLITE_UTF8 ){
   142    142             memset(&utf8, 0, sizeof(utf8));
   143    143             utf8.db = db;
   144         -          if( SQLITE_NOMEM== sqlite3VdbeMemSetStr(&utf8,pVar->z,pVar->n,enc,SQLITE_STATIC)
   145         -           || SQLITE_NOMEM== sqlite3VdbeChangeEncoding(&utf8, SQLITE_UTF8)
          144  +          if( SQLITE_NOMEM==sqlite3VdbeMemSetStr(&utf8,pVar->z,pVar->n,enc,SQLITE_STATIC)
          145  +           || SQLITE_NOMEM==sqlite3VdbeChangeEncoding(&utf8, SQLITE_UTF8)
   146    146             ){
   147    147               sqlite3StrAccumReset(&out);
   148    148               sqlite3VdbeMemRelease(&utf8);
   149    149               return 0;
   150    150             }
   151    151             pVar = &utf8;
   152    152           }