/ Check-in [0400f642]
Login

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

Overview
Comment:Improvements to sqlite3_trace_v2() documentation. Fix the sqlite3VdbeExpandSql() routine to respond better to OOM conditions.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | sqlite3_trace_v2
Files: files | file ages | folders
SHA1: 0400f642d542e62bb428e0bf263964c65691368e
User & Date: drh 2016-07-23 04:58:57
Context
2016-07-23
05:22
Add the sqlite3_expanded_sql() and sqlite3_trace_v2() interfaces. check-in: 99a6c518 user: drh tags: trunk
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
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
....
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
....
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515



3516
3517
3518
3519
3520
3521
3522
** is the expanded SQL text of the prepared statement or a comment that
** indicates the invocation of a trigger.
**
** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
** information as is provided by the [sqlite3_profile()] callback.
** ^The P argument is a pointer to the [prepared statement] and the
** ^X argument points to a 64-bit integer which is the estimated of
** the number of nanosecond that the prepared statement took to run.
** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
**
** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
** statement generates a single row of result.  
** ^The P argument is a pointer to the [prepared statement] and the
................................................................................
** CAPI3REF: SQL Trace Hook
** METHOD: sqlite3
**
** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
** function X against [database connection] D, using property mask M
** and context pointer P.  ^If the X callback is
** NULL or if the M mask is zero, then tracing is disabled.  The
** M argument must be one or more of the [SQLITE_TRACE]
** constants.
**
** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides 
** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
**
** ^The X callback is invoked whenever any of the events identified by 
** mask M occur.  ^The integer return value from the callback is currently
** ignored, though this may change in future releases.  Callback
................................................................................
**
** ^(For example, if a prepared statement is created using the SQL
** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
** and parameter :xyz is unbound, then sqlite3_sql() will return
** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
** will return "SELECT 2345,NULL".)^
**
** ^The [SQLITE_TRACE_SIZE_LIMIT] setting limits the size of a 
** bound parameter expansion.  ^If SQLite is built with the
** [SQLITE_OMIT_TRACE] compile-time option then the sqlite3_expanded_sql()
** interface is non-functional and always returns NULL.



**
** ^The string returned by sqlite3_sql(P) is managed by SQLite and is
** automatically freed when the prepared statement is finalized.
** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
** is obtained from [sqlite3_malloc()] and must be free by the application
** by passing it to [sqlite3_free()].
*/







|







 







|
|







 







|
|
|
|
>
>
>







2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
....
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
....
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
** is the expanded SQL text of the prepared statement or a comment that
** indicates the invocation of a trigger.
**
** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
** information as is provided by the [sqlite3_profile()] callback.
** ^The P argument is a pointer to the [prepared statement] and the
** X argument points to a 64-bit integer which is the estimated of
** the number of nanosecond that the prepared statement took to run.
** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
**
** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
** statement generates a single row of result.  
** ^The P argument is a pointer to the [prepared statement] and the
................................................................................
** CAPI3REF: SQL Trace Hook
** METHOD: sqlite3
**
** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
** function X against [database connection] D, using property mask M
** and context pointer P.  ^If the X callback is
** NULL or if the M mask is zero, then tracing is disabled.  The
** M argument should be the bitwise OR-ed combination of
** zero or more [SQLITE_TRACE] constants.
**
** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides 
** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
**
** ^The X callback is invoked whenever any of the events identified by 
** mask M occur.  ^The integer return value from the callback is currently
** ignored, though this may change in future releases.  Callback
................................................................................
**
** ^(For example, if a prepared statement is created using the SQL
** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
** and parameter :xyz is unbound, then sqlite3_sql() will return
** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
** will return "SELECT 2345,NULL".)^
**
** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory
** is available to hold the result, or if the result would exceed the
** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].
**
** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
** bound parameter expansions.  ^The [SQLITE_OMIT_TRACE] compile-time
** option causes sqlite3_expanded_sql() to always return NULL.
**
** ^The string returned by sqlite3_sql(P) is managed by SQLite and is
** automatically freed when the prepared statement is finalized.
** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
** is obtained from [sqlite3_malloc()] and must be free by the application
** by passing it to [sqlite3_free()].
*/

Changes to src/vdbetrace.c.

137
138
139
140
141
142
143
144
145
146

147
148
149
150
151
152
153
154
155
156
...
185
186
187
188
189
190
191

192
193
194
195
      }else if( pVar->flags & MEM_Str ){
        int nOut;  /* Number of bytes of the string text to include in output */
#ifndef SQLITE_OMIT_UTF16
        u8 enc = ENC(db);
        if( enc!=SQLITE_UTF8 ){
          memset(&utf8, 0, sizeof(utf8));
          utf8.db = db;
          if( SQLITE_NOMEM==sqlite3VdbeMemSetStr(&utf8,pVar->z,pVar->n,enc,SQLITE_STATIC)
           || SQLITE_NOMEM==sqlite3VdbeChangeEncoding(&utf8, SQLITE_UTF8)
          ){

            sqlite3StrAccumReset(&out);
            sqlite3VdbeMemRelease(&utf8);
            return 0;
          }
          pVar = &utf8;
        }
#endif
        nOut = pVar->n;
#ifdef SQLITE_TRACE_SIZE_LIMIT
        if( nOut>SQLITE_TRACE_SIZE_LIMIT ){
................................................................................
        if( nOut<pVar->n ){
          sqlite3XPrintf(&out, "/*+%d bytes*/", pVar->n-nOut);
        }
#endif
      }
    }
  }

  return sqlite3StrAccumFinish(&out);
}

#endif /* #ifndef SQLITE_OMIT_TRACE */







|
|
<
>
|
<
<







 







>




137
138
139
140
141
142
143
144
145

146
147


148
149
150
151
152
153
154
...
183
184
185
186
187
188
189
190
191
192
193
194
      }else if( pVar->flags & MEM_Str ){
        int nOut;  /* Number of bytes of the string text to include in output */
#ifndef SQLITE_OMIT_UTF16
        u8 enc = ENC(db);
        if( enc!=SQLITE_UTF8 ){
          memset(&utf8, 0, sizeof(utf8));
          utf8.db = db;
          sqlite3VdbeMemSetStr(&utf8, pVar->z, pVar->n, enc, SQLITE_STATIC);
          if( SQLITE_NOMEM==sqlite3VdbeChangeEncoding(&utf8, SQLITE_UTF8) ){

            out.accError = STRACCUM_NOMEM;
            out.nAlloc = 0;


          }
          pVar = &utf8;
        }
#endif
        nOut = pVar->n;
#ifdef SQLITE_TRACE_SIZE_LIMIT
        if( nOut>SQLITE_TRACE_SIZE_LIMIT ){
................................................................................
        if( nOut<pVar->n ){
          sqlite3XPrintf(&out, "/*+%d bytes*/", pVar->n-nOut);
        }
#endif
      }
    }
  }
  if( out.accError ) sqlite3StrAccumReset(&out);
  return sqlite3StrAccumFinish(&out);
}

#endif /* #ifndef SQLITE_OMIT_TRACE */