Sq3StmtC_TOR_C_API

Sq3StmtC - various functions to create, initialize and destroy … More...

Collaboration diagram for Sq3StmtC_TOR_C_API:

Functions
static enum MkErrorE	Sq3LitePrepareV2 (SQ3_LITE db, MkStringR zSql, SQ3_STMT *ppStmt)
	Compiling An SQL Statement …
static enum MkErrorE	Sq3StmtPrepareV2Hide (SQ3_LITE db, MK_STRN zSql, MK_I32 nByte, SQ3_STMT *ppStmt, MK_STRN *pzTail)
	Compiling An SQL Statement …
static enum MkErrorE	Sq3StmtPrepareV3Hide (SQ3_LITE db, MK_STRN zSql, MK_I32 nByte, enum Sq3PrepareEF prepFlags, SQ3_STMT *ppStmt, MK_STRN *pzTail)
	Compiling An SQL Statement …
static enum MkErrorE	Sq3StmtFinalize (SQ3_STMT pStmt)
	Destroy A Prepared Statement Object …
static enum MkErrorE	Sq3StmtPrepareV2 (SQ3_LITE db, MkStringR zSql, SQ3_STMT *ppStmt)
	Compiling An SQL Statement …
static enum MkErrorE	Sq3StmtPrepareV3 (SQ3_LITE db, MkStringR zSql, Sq3PrepareEF prepFlags, SQ3_STMT *ppStmt)
	Compiling An SQL Statement …

Sq3StmtC - Sq3StmtC_TOR_C_API - function
enum MkErrorE	Sq3StmtPrepareV2HideP (SQ3_LITE db, MK_STRN zSql, MK_I32 nByte, SQ3_STMT *ppStmt, MK_STRN *pzTail)
	Non-inline replacement for Sq3StmtPrepareV2Hide …
enum MkErrorE	Sq3StmtPrepareV3HideP (SQ3_LITE db, MK_STRN zSql, MK_I32 nByte, enum Sq3PrepareEF prepFlags, SQ3_STMT *ppStmt, MK_STRN *pzTail)
	Non-inline replacement for Sq3StmtPrepareV3Hide …
enum MkErrorE	Sq3StmtPrepareV2P (SQ3_LITE db, MkStringR zSql, SQ3_STMT *ppStmt)
	Non-inline replacement for Sq3StmtPrepareV2 …
enum MkErrorE	Sq3StmtPrepareV3P (SQ3_LITE db, MkStringR zSql, enum Sq3PrepareEF prepFlags, SQ3_STMT *ppStmt)
	Non-inline replacement for Sq3StmtPrepareV3 …
enum MkErrorE	Sq3StmtFinalizeP (SQ3_STMT pStmt)
	Non-inline replacement for Sq3StmtFinalize …

Sq3StmtC - Sq3StmtC_TOR_C_API - overload
#define	Sq3StmtPrepareV2Hide_4(db, zSql, ppStmt, pzTail)
#define	Sq3StmtPrepareV2Hide_E(...)
#define	Sq3StmtPrepareV2Hide_C(...)
#define	Sq3StmtPrepareV3Hide_5(db, zSql, nByte, ppStmt, pzTail)
#define	Sq3StmtPrepareV3Hide_4(db, zSql, ppStmt, pzTail)
#define	Sq3StmtPrepareV3Hide_E(...)
#define	Sq3StmtPrepareV3Hide_C(...)
#define	Sq3StmtPrepareV2_E(...)
#define	Sq3StmtPrepareV2_C(...)
#define	Sq3StmtPrepareV2_e(...)
#define	Sq3StmtPrepareV3_3(db, zSql, ppStmt)
#define	Sq3StmtPrepareV3_E(...)
#define	Sq3StmtPrepareV3_C(...)
#define	Sq3StmtPrepareV3_e(...)
#define	Sq3StmtFinalize_E(...)
#define	Sq3StmtFinalize_C(...)

Detailed Description

Sq3StmtC - various functions to create, initialize and destroy …

Macro Definition Documentation

Sq3StmtFinalize_C

#define Sq3StmtFinalize_C

(

...

)

Value:

if (MkErrorCheckI(Sq3StmtFinalize(__VA_ARGS__)))

Definition at line 670 of file sqlite3_overload_sq3.h.

Sq3StmtFinalize_E

#define Sq3StmtFinalize_E

(

...

)

Value:

MkErrorCheck(Sq3StmtFinalize(__VA_ARGS__))

Definition at line 669 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV2_C

#define Sq3StmtPrepareV2_C

(

...

)

Value:

if (MkErrorCheckI(Sq3StmtPrepareV2(__VA_ARGS__)))

Definition at line 661 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV2_E

#define Sq3StmtPrepareV2_E

(

...

)

Value:

MkErrorCheck(Sq3StmtPrepareV2(__VA_ARGS__))

Definition at line 660 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV2_e

#define Sq3StmtPrepareV2_e

(

...

)

Value:

MK_EMBEDDED(SQ3_STMT,Sq3StmtPrepareV2,__VA_ARGS__)

Definition at line 662 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV2Hide_4

#define Sq3StmtPrepareV2Hide_4	(		db,
			zSql,
			ppStmt,
			pzTail )

Value:

Sq3StmtPrepareV2Hide(db,zSql,-1,ppStmt,pzTail)

Definition at line 651 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV2Hide_C

#define Sq3StmtPrepareV2Hide_C

(

...

)

Value:

if (MkErrorCheckI(Sq3StmtPrepareV2Hide(__VA_ARGS__)))

Definition at line 653 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV2Hide_E

#define Sq3StmtPrepareV2Hide_E

(

...

)

Value:

MkErrorCheck(Sq3StmtPrepareV2Hide(__VA_ARGS__))

Definition at line 652 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV3_3

#define Sq3StmtPrepareV3_3	(		db,
			zSql,
			ppStmt )

Value:

Sq3StmtPrepareV3(db,zSql,SQ3_PREPARE_NO,ppStmt)

Definition at line 663 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV3_C

#define Sq3StmtPrepareV3_C

(

...

)

Value:

if (MkErrorCheckI(Sq3StmtPrepareV3(__VA_ARGS__)))

Definition at line 665 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV3_E

#define Sq3StmtPrepareV3_E

(

...

)

Value:

MkErrorCheck(Sq3StmtPrepareV3(__VA_ARGS__))

Definition at line 664 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV3_e

#define Sq3StmtPrepareV3_e

(

...

)

Value:

MK_EMBEDDED(SQ3_STMT,Sq3StmtPrepareV3,__VA_ARGS__)

Definition at line 666 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV3Hide_4

#define Sq3StmtPrepareV3Hide_4	(		db,
			zSql,
			ppStmt,
			pzTail )

Value:

Sq3StmtPrepareV3Hide(db,zSql,-1,SQ3_PREPARE_NO,ppStmt,pzTail)

Definition at line 655 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV3Hide_5

#define Sq3StmtPrepareV3Hide_5	(		db,
			zSql,
			nByte,
			ppStmt,
			pzTail )

Value:

Sq3StmtPrepareV3Hide(db,zSql,nByte,SQ3_PREPARE_NO,ppStmt,pzTail)

Definition at line 654 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV3Hide_C

#define Sq3StmtPrepareV3Hide_C

(

...

)

Value:

if (MkErrorCheckI(Sq3StmtPrepareV3Hide(__VA_ARGS__)))

Definition at line 657 of file sqlite3_overload_sq3.h.

Sq3StmtPrepareV3Hide_E

#define Sq3StmtPrepareV3Hide_E

(

...

)

Value:

MkErrorCheck(Sq3StmtPrepareV3Hide(__VA_ARGS__))

Definition at line 656 of file sqlite3_overload_sq3.h.

Function Documentation

Sq3LitePrepareV2()

static enum MkErrorE Sq3LitePrepareV2 ( SQ3_LITE db, MkStringR zSql, SQ3_STMT * ppStmt )

inlinestatic

Compiling An SQL Statement …

This is an enhanced version of Sq3StmtPrepareV2Hide. The last argument pzTail is stored into the Sq3StmtC class Sq3StmtS::pzTail attribute and can be accessed with Sq3StmtGetPzTail.

Parameters

[in]	db	the Sq3LiteC instance to work on a database
[in]	zSql	The statement to be compiled, encoded as UTF-8
[out]	ppStmt	The new Sq3StmtC instance

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Sq3StmtPrepareV2Hide : documentation

Compiling An SQL Statement …

To execute an SQL statement, it must first be compiled into a byte-code program using one of these routines. Or, in other words, these routines are constructors for the prepared statement object.

The preferred routine to use is Sq3StmtPrepareV2 (). The sqlite3_prepare () interface is legacy and should be avoided. Sq3StmtPrepareV3 () has an extra "prepFlags" option that is used for special purposes.

The use of the UTF-8 interfaces is preferred, as SQLite currently does all parsing using UTF-8. The UTF-16 interfaces are provided as a convenience. The UTF-16 interfaces work by converting the input text into UTF-8, then invoking the corresponding UTF-8 interface.

The first argument, "db", is a database connection obtained from a prior successful call to sqlite3_open (), Sq3LiteOpenV2 () or sqlite3_open16 (). The database connection must not have been closed.

The second argument, "zSql", is the statement to be compiled, encoded as either UTF-8 or UTF-16. The sqlite3_prepare(), Sq3StmtPrepareV2(), and Sq3StmtPrepareV3() interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(), and sqlite3_prepare16_v3() use UTF-16.

If the nByte argument is negative, then zSql is read up to the first zero terminator. If nByte is positive, then it is the number of bytes read from zSql. If nByte is zero, then no prepared statement is generated. If the caller knows that the supplied string is nul-terminated, then there is a small performance advantage to passing an nByte parameter that is the number of bytes in the input string including the nul-terminator.

If pzTail is not NULL then *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 Sq3StmtStep (). 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. The calling procedure is responsible for deleting the compiled SQL statement using Sq3StmtFinalize () after it has finished with it. ppStmt may not be NULL.

On success, the sqlite3_prepare() family of routines return SQ3_RESULT_OK; otherwise an error code is returned.

The Sq3StmtPrepareV2(), Sq3StmtPrepareV3(), sqlite3_prepare16_v2(), and sqlite3_prepare16_v3() interfaces are recommended for all new programs. The older interfaces (sqlite3_prepare() and sqlite3_prepare16()) are retained for backwards compatibility, but their use is discouraged. In the "vX" interfaces, the prepared statement that is returned (the Sq3StmtC object) contains a copy of the original SQL text. This causes the Sq3StmtStep () interface to behave differently in three ways:

1. If the database schema changes, instead of returning SQ3_RESULT_SCHEMA as it always used to do, Sq3StmtStep () will automatically recompile the SQL statement and try to run it again. As many as SQLITE_MAX_SCHEMA_RETRY retries will occur before Sq3StmtStep() gives up and returns an error.

2. When an error occurs, Sq3StmtStep () will return one of the detailed error codes or extended error codes. The legacy behavior was that Sq3StmtStep () would only return a generic SQ3_RESULT_ERROR result code and the application would have to make a second call to Sq3StmtReset () in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.

3. If the specific value bound to a host parameter in the WHERE clause might influence the choice of query plan for a statement, then the statement will be automatically recompiled, as if there had been a schema change, on the first Sq3StmtStep () call following any change to the bindings of that parameter. The specific value of a WHERE-clause parameter might influence the choice of query plan if the parameter is the left-hand side of a LIKE or GLOB operator or if the parameter is compared to an indexed column and the SQLITE_ENABLE_STAT4 compile-time option is enabled.

Sq3StmtPrepareV3() differs from Sq3StmtPrepareV2() only in having the extra prepFlags parameter, which is a bit array consisting of zero or more of the SQ3_PREPARE_* flags. The Sq3StmtPrepareV2() interface works exactly the same as Sq3StmtPrepareV3() with a zero prepFlags parameter.

Reference code from sqlite3:

SQLITE_API 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 
);
SQLITE_API int sqlite3_prepare_v2(
  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 
);
SQLITE_API int sqlite3_prepare_v3(
  sqlite3 *db,            // Database handle 
  const char *zSql,       // SQL statement, UTF-8 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  unsigned int prepFlags, // Zero or more SQLITE_PREPARE_ flags 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const char **pzTail     // OUT: Pointer to unused portion of zSql 
);
SQLITE_API int sqlite3_prepare16(
  sqlite3 *db,            // Database handle 
  const void *zSql,       // SQL statement, UTF-16 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const void **pzTail     // OUT: Pointer to unused portion of zSql 
);
SQLITE_API int sqlite3_prepare16_v2(
  sqlite3 *db,            // Database handle 
  const void *zSql,       // SQL statement, UTF-16 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const void **pzTail     // OUT: Pointer to unused portion of zSql 
);
SQLITE_API int sqlite3_prepare16_v3(
  sqlite3 *db,            // Database handle 
  const void *zSql,       // SQL statement, UTF-16 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  unsigned int prepFlags, // Zero or more SQLITE_PREPARE_ flags 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const void **pzTail     // OUT: Pointer to unused portion of zSql 
);

Definition at line 710 of file Sq3LiteC_sq3.h.

  {
  SQ3_INSTANCE_HDL(db);
  MkRtSetup_X(db);
  MK_STRN pzTail = NULL;
  MkErrorE_Check(Sq3StmtPrepareV2Hide(db,zSql.ptr,zSql.len,ppStmt,&pzTail));
  (*ppStmt)->pzTail = pzTail;
  MkErrorReturnLabel(db);
} 

Here is the caller graph for this function:

Sq3StmtFinalize()

static enum MkErrorE Sq3StmtFinalize ( SQ3_STMT pStmt )

inlinestatic

Destroy A Prepared Statement Object …

The Sq3StmtFinalize() function is called to delete a prepared statement. If the most recent evaluation of the statement encountered no errors or if the statement is never been evaluated, then Sq3StmtFinalize() returns SQ3_RESULT_OK. If the most recent evaluation of statement S failed, then Sq3StmtFinalize(S) returns the appropriate error code or extended error code.

The Sq3StmtFinalize(S) routine can be called at any point during the life cycle of prepared statement S: before statement S is ever evaluated, after one or more calls to Sq3StmtReset (), or after any call to Sq3StmtStep () regardless of whether or not the statement has completed execution.

Invoking Sq3StmtFinalize() on a NULL pointer is a harmless no-op.

The application must finalize every prepared statement in order to avoid resource leaks. It is a grievous error for the application to try to use a prepared statement after it has been finalized. Any use of a prepared statement after it has been finalized can result in undefined and undesirable behavior such as segfaults and heap corruption.

Reference code from sqlite3:

SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);

Definition at line 457 of file Sq3StmtC_sq3.h.

                                                           {
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_finalize(pStmt->nat);
    Sq3ErrorE_Check(pStmt, errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3StmtFinalizeP()

enum MkErrorE Sq3StmtFinalizeP

(

SQ3_STMT

pStmt

)

Non-inline replacement for Sq3StmtFinalize …

Sq3StmtPrepareV2()

static enum MkErrorE Sq3StmtPrepareV2 ( SQ3_LITE db, MkStringR zSql, SQ3_STMT * ppStmt )

inlinestatic

Compiling An SQL Statement …

This is an enhanced version of Sq3StmtPrepareV2Hide using the Programming-Language-Micro-Kernel (PLMK) definition of a zSql called MkStringR. The last argument pzTail is stored into the Sq3StmtC class Sq3StmtS::pzTail attribute and can be accessed with Sq3StmtGetPzTail.

Parameters

[in]	db	the Sq3LiteC instance to work on a database
[in]	zSql	The statement to be compiled, encoded as UTF-8
[out]	ppStmt	The new Sq3StmtC instance

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Sq3StmtPrepareV2Hide : documentation

Compiling An SQL Statement …

To execute an SQL statement, it must first be compiled into a byte-code program using one of these routines. Or, in other words, these routines are constructors for the prepared statement object.

The preferred routine to use is Sq3StmtPrepareV2 (). The sqlite3_prepare () interface is legacy and should be avoided. Sq3StmtPrepareV3 () has an extra "prepFlags" option that is used for special purposes.

The use of the UTF-8 interfaces is preferred, as SQLite currently does all parsing using UTF-8. The UTF-16 interfaces are provided as a convenience. The UTF-16 interfaces work by converting the input text into UTF-8, then invoking the corresponding UTF-8 interface.

The first argument, "db", is a database connection obtained from a prior successful call to sqlite3_open (), Sq3LiteOpenV2 () or sqlite3_open16 (). The database connection must not have been closed.

The second argument, "zSql", is the statement to be compiled, encoded as either UTF-8 or UTF-16. The sqlite3_prepare(), Sq3StmtPrepareV2(), and Sq3StmtPrepareV3() interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(), and sqlite3_prepare16_v3() use UTF-16.

If the nByte argument is negative, then zSql is read up to the first zero terminator. If nByte is positive, then it is the number of bytes read from zSql. If nByte is zero, then no prepared statement is generated. If the caller knows that the supplied string is nul-terminated, then there is a small performance advantage to passing an nByte parameter that is the number of bytes in the input string including the nul-terminator.

If pzTail is not NULL then *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 Sq3StmtStep (). 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. The calling procedure is responsible for deleting the compiled SQL statement using Sq3StmtFinalize () after it has finished with it. ppStmt may not be NULL.

On success, the sqlite3_prepare() family of routines return SQ3_RESULT_OK; otherwise an error code is returned.

The Sq3StmtPrepareV2(), Sq3StmtPrepareV3(), sqlite3_prepare16_v2(), and sqlite3_prepare16_v3() interfaces are recommended for all new programs. The older interfaces (sqlite3_prepare() and sqlite3_prepare16()) are retained for backwards compatibility, but their use is discouraged. In the "vX" interfaces, the prepared statement that is returned (the Sq3StmtC object) contains a copy of the original SQL text. This causes the Sq3StmtStep () interface to behave differently in three ways:

1. If the database schema changes, instead of returning SQ3_RESULT_SCHEMA as it always used to do, Sq3StmtStep () will automatically recompile the SQL statement and try to run it again. As many as SQLITE_MAX_SCHEMA_RETRY retries will occur before Sq3StmtStep() gives up and returns an error.

2. When an error occurs, Sq3StmtStep () will return one of the detailed error codes or extended error codes. The legacy behavior was that Sq3StmtStep () would only return a generic SQ3_RESULT_ERROR result code and the application would have to make a second call to Sq3StmtReset () in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.

3. If the specific value bound to a host parameter in the WHERE clause might influence the choice of query plan for a statement, then the statement will be automatically recompiled, as if there had been a schema change, on the first Sq3StmtStep () call following any change to the bindings of that parameter. The specific value of a WHERE-clause parameter might influence the choice of query plan if the parameter is the left-hand side of a LIKE or GLOB operator or if the parameter is compared to an indexed column and the SQLITE_ENABLE_STAT4 compile-time option is enabled.

Sq3StmtPrepareV3() differs from Sq3StmtPrepareV2() only in having the extra prepFlags parameter, which is a bit array consisting of zero or more of the SQ3_PREPARE_* flags. The Sq3StmtPrepareV2() interface works exactly the same as Sq3StmtPrepareV3() with a zero prepFlags parameter.

Reference code from sqlite3:

SQLITE_API 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 
);
SQLITE_API int sqlite3_prepare_v2(
  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 
);
SQLITE_API int sqlite3_prepare_v3(
  sqlite3 *db,            // Database handle 
  const char *zSql,       // SQL statement, UTF-8 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  unsigned int prepFlags, // Zero or more SQLITE_PREPARE_ flags 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const char **pzTail     // OUT: Pointer to unused portion of zSql 
);
SQLITE_API int sqlite3_prepare16(
  sqlite3 *db,            // Database handle 
  const void *zSql,       // SQL statement, UTF-16 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const void **pzTail     // OUT: Pointer to unused portion of zSql 
);
SQLITE_API int sqlite3_prepare16_v2(
  sqlite3 *db,            // Database handle 
  const void *zSql,       // SQL statement, UTF-16 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const void **pzTail     // OUT: Pointer to unused portion of zSql 
);
SQLITE_API int sqlite3_prepare16_v3(
  sqlite3 *db,            // Database handle 
  const void *zSql,       // SQL statement, UTF-16 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  unsigned int prepFlags, // Zero or more SQLITE_PREPARE_ flags 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const void **pzTail     // OUT: Pointer to unused portion of zSql 
);

Definition at line 487 of file Sq3StmtC_sq3.h.

  {
  assert (db != NULL);
  MkRtSetup_XN(db);
  MK_STRN pzTail = NULL;
  MkErrorE_Check(Sq3StmtPrepareV2Hide(db,zSql.ptr,zSql.len,ppStmt,&pzTail));
  (*ppStmt)->pzTail = pzTail;
  MkErrorReturnLabel(db);
} 

Here is the caller graph for this function:

Sq3StmtPrepareV2Hide()

static enum MkErrorE Sq3StmtPrepareV2Hide ( SQ3_LITE db, MK_STRN zSql, MK_I32 nByte, SQ3_STMT * ppStmt, MK_STRN * pzTail )

inlinestatic

Compiling An SQL Statement …

To execute an SQL statement, it must first be compiled into a byte-code program using one of these routines. Or, in other words, these routines are constructors for the prepared statement object.

The preferred routine to use is Sq3StmtPrepareV2 (). The sqlite3_prepare () interface is legacy and should be avoided. Sq3StmtPrepareV3 () has an extra "prepFlags" option that is used for special purposes.

The use of the UTF-8 interfaces is preferred, as SQLite currently does all parsing using UTF-8. The UTF-16 interfaces are provided as a convenience. The UTF-16 interfaces work by converting the input text into UTF-8, then invoking the corresponding UTF-8 interface.

The first argument, "db", is a database connection obtained from a prior successful call to sqlite3_open (), Sq3LiteOpenV2 () or sqlite3_open16 (). The database connection must not have been closed.

The second argument, "zSql", is the statement to be compiled, encoded as either UTF-8 or UTF-16. The sqlite3_prepare(), Sq3StmtPrepareV2(), and Sq3StmtPrepareV3() interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(), and sqlite3_prepare16_v3() use UTF-16.

If the nByte argument is negative, then zSql is read up to the first zero terminator. If nByte is positive, then it is the number of bytes read from zSql. If nByte is zero, then no prepared statement is generated. If the caller knows that the supplied string is nul-terminated, then there is a small performance advantage to passing an nByte parameter that is the number of bytes in the input string including the nul-terminator.

If pzTail is not NULL then *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 Sq3StmtStep (). 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. The calling procedure is responsible for deleting the compiled SQL statement using Sq3StmtFinalize () after it has finished with it. ppStmt may not be NULL.

On success, the sqlite3_prepare() family of routines return SQ3_RESULT_OK; otherwise an error code is returned.

The Sq3StmtPrepareV2(), Sq3StmtPrepareV3(), sqlite3_prepare16_v2(), and sqlite3_prepare16_v3() interfaces are recommended for all new programs. The older interfaces (sqlite3_prepare() and sqlite3_prepare16()) are retained for backwards compatibility, but their use is discouraged. In the "vX" interfaces, the prepared statement that is returned (the Sq3StmtC object) contains a copy of the original SQL text. This causes the Sq3StmtStep () interface to behave differently in three ways:

1. If the database schema changes, instead of returning SQ3_RESULT_SCHEMA as it always used to do, Sq3StmtStep () will automatically recompile the SQL statement and try to run it again. As many as SQLITE_MAX_SCHEMA_RETRY retries will occur before Sq3StmtStep() gives up and returns an error.

2. When an error occurs, Sq3StmtStep () will return one of the detailed error codes or extended error codes. The legacy behavior was that Sq3StmtStep () would only return a generic SQ3_RESULT_ERROR result code and the application would have to make a second call to Sq3StmtReset () in order to find the underlying cause of the problem. With the "v2" prepare interfaces, the underlying reason for the error is returned immediately.

3. If the specific value bound to a host parameter in the WHERE clause might influence the choice of query plan for a statement, then the statement will be automatically recompiled, as if there had been a schema change, on the first Sq3StmtStep () call following any change to the bindings of that parameter. The specific value of a WHERE-clause parameter might influence the choice of query plan if the parameter is the left-hand side of a LIKE or GLOB operator or if the parameter is compared to an indexed column and the SQLITE_ENABLE_STAT4 compile-time option is enabled.

Sq3StmtPrepareV3() differs from Sq3StmtPrepareV2() only in having the extra prepFlags parameter, which is a bit array consisting of zero or more of the SQ3_PREPARE_* flags. The Sq3StmtPrepareV2() interface works exactly the same as Sq3StmtPrepareV3() with a zero prepFlags parameter.

Reference code from sqlite3:

SQLITE_API 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 
);
SQLITE_API int sqlite3_prepare_v2(
  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 
);
SQLITE_API int sqlite3_prepare_v3(
  sqlite3 *db,            // Database handle 
  const char *zSql,       // SQL statement, UTF-8 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  unsigned int prepFlags, // Zero or more SQLITE_PREPARE_ flags 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const char **pzTail     // OUT: Pointer to unused portion of zSql 
);
SQLITE_API int sqlite3_prepare16(
  sqlite3 *db,            // Database handle 
  const void *zSql,       // SQL statement, UTF-16 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const void **pzTail     // OUT: Pointer to unused portion of zSql 
);
SQLITE_API int sqlite3_prepare16_v2(
  sqlite3 *db,            // Database handle 
  const void *zSql,       // SQL statement, UTF-16 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const void **pzTail     // OUT: Pointer to unused portion of zSql 
);
SQLITE_API int sqlite3_prepare16_v3(
  sqlite3 *db,            // Database handle 
  const void *zSql,       // SQL statement, UTF-16 encoded 
  int nByte,              // Maximum length of zSql in bytes. 
  unsigned int prepFlags, // Zero or more SQLITE_PREPARE_ flags 
  sqlite3_stmt **ppStmt,  // OUT: Statement handle 
  const void **pzTail     // OUT: Pointer to unused portion of zSql 
);

Definition at line 429 of file Sq3StmtC_sq3.h.

                                                                                                                            {
    *ppStmt = NULL;
    struct sqlite3 * db_hdl = db->nat;
    sqlite3_stmt* ppStmt_val = NULL;
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_prepare_v2(db_hdl, zSql, nByte, &ppStmt_val, pzTail);
    *ppStmt = Sq3StmtC_ObjCreate(ppStmt_val);
    Sq3ErrorE_Check_Static(Sq3StmtC_TT,errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3StmtPrepareV2HideP()

enum MkErrorE Sq3StmtPrepareV2HideP	(	SQ3_LITE	db,
		MK_STRN	zSql,
		MK_I32	nByte,
		SQ3_STMT *	ppStmt,
		MK_STRN *	pzTail )

Non-inline replacement for Sq3StmtPrepareV2Hide …

Sq3StmtPrepareV2P()

enum MkErrorE Sq3StmtPrepareV2P	(	SQ3_LITE	db,
		MkStringR	zSql,
		SQ3_STMT *	ppStmt )

Non-inline replacement for Sq3StmtPrepareV2 …

Sq3StmtPrepareV3()

static enum MkErrorE Sq3StmtPrepareV3 ( SQ3_LITE db, MkStringR zSql, Sq3PrepareEF prepFlags, SQ3_STMT * ppStmt )

inlinestatic

Compiling An SQL Statement …

This is an enhanced version of Sq3StmtPrepareV2Hide using the Programming-Language-Micro-Kernel (PLMK) definition of a zSql called MkStringR. The last argument pzTail is stored into the Sq3StmtC class Sq3StmtS::pzTail attribute and can be accessed with Sq3StmtGetPzTail.

Parameters

[in]	db	the Sq3LiteC instance to work on a database
[in]	zSql	The statement to be compiled, encoded as UTF-8
[in]	prepFlags	Is a bit array consisting of zero or more of the SQ3_PREPARE_* flags.
[out]	ppStmt	The new Sq3StmtC instance

Exceptions

MkExceptionC

→ The default-exception from the Programming-Language-Micro-Kernel (PLMK)

Sq3StmtPrepareV3Hide : documentation

Compiling An SQL Statement …

read more at 'Sq3StmtPrepareV2'

Definition at line 516 of file Sq3StmtC_sq3.h.

  {
  assert (db != NULL);
  MkRtSetup_XN(db);
  MK_STRN pzTail = NULL;
  MkErrorE_Check(Sq3StmtPrepareV3Hide(db,zSql.ptr,zSql.len,prepFlags,ppStmt,&pzTail));
  (*ppStmt)->pzTail = pzTail;
  MkErrorReturnLabel(db);
} 

Here is the caller graph for this function:

Sq3StmtPrepareV3Hide()

static enum MkErrorE Sq3StmtPrepareV3Hide ( SQ3_LITE db, MK_STRN zSql, MK_I32 nByte, enum Sq3PrepareEF prepFlags, SQ3_STMT * ppStmt, MK_STRN * pzTail )

inlinestatic

Compiling An SQL Statement …

read more at 'Sq3StmtPrepareV2'

Definition at line 442 of file Sq3StmtC_sq3.h.

                                                                                                                                                         {
    *ppStmt = NULL;
    struct sqlite3 * db_hdl = db->nat;
    sqlite3_stmt* ppStmt_val = NULL;
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_prepare_v3(db_hdl, zSql, nByte, prepFlags, &ppStmt_val, pzTail);
    *ppStmt = Sq3StmtC_ObjCreate(ppStmt_val);
    Sq3ErrorE_Check_Static(Sq3StmtC_TT,errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3StmtPrepareV3HideP()

enum MkErrorE Sq3StmtPrepareV3HideP	(	SQ3_LITE	db,
		MK_STRN	zSql,
		MK_I32	nByte,
		enum Sq3PrepareEF	prepFlags,
		SQ3_STMT *	ppStmt,
		MK_STRN *	pzTail )

Non-inline replacement for Sq3StmtPrepareV3Hide …

Sq3StmtPrepareV3P()

enum MkErrorE Sq3StmtPrepareV3P	(	SQ3_LITE	db,
		MkStringR	zSql,
		enum Sq3PrepareEF	prepFlags,
		SQ3_STMT *	ppStmt )

Non-inline replacement for Sq3StmtPrepareV3 …