Sq3StmtC_Misc_C_API

Sq3StmtC - various functions to perform misc operations … More...

Collaboration diagram for Sq3StmtC_Misc_C_API:

Functions
static SQ3_STMT	Sq3StmtNextStmt (SQ3_LITE pDb, SQ3_STMT pStmt)
	Find the next prepared statement …
static enum MkErrorE	Sq3StmtClearBindings (SQ3_STMT sq3stmt)
	Reset All Bindings On A Prepared Statement …
static enum MkErrorE	Sq3StmtExplain (SQ3_STMT pStmt, MK_I32 eMode)
	Change The EXPLAIN Setting For A Prepared Statement …
static enum MkErrorE	Sq3StmtReset (SQ3_STMT pStmt)
	Reset A Prepared Statement Object …
static enum MkErrorE	Sq3StmtStep (SQ3_STMT sq3stmt, enum Sq3ErrorE *retCode)
	Evaluate An SQL Statement …

Sq3StmtC - Sq3StmtC_Misc_C_API - function
SQ3_STMT	Sq3StmtNextStmtP (SQ3_LITE pDb, SQ3_STMT pStmt)
	Non-inline replacement for Sq3StmtNextStmt …
enum MkErrorE	Sq3StmtClearBindingsP (SQ3_STMT sq3stmt)
	Non-inline replacement for Sq3StmtClearBindings …
enum MkErrorE	Sq3StmtExplainP (SQ3_STMT pStmt, MK_I32 eMode)
	Non-inline replacement for Sq3StmtExplain …
enum MkErrorE	Sq3StmtResetP (SQ3_STMT pStmt)
	Non-inline replacement for Sq3StmtReset …
enum MkErrorE	Sq3StmtStepP (SQ3_STMT sq3stmt, enum Sq3ErrorE *retCode)
	Non-inline replacement for Sq3StmtStep …

Sq3StmtC - Sq3StmtC_Misc_C_API - overload
#define	Sq3StmtNextStmt_1(pDb)
#define	Sq3StmtClearBindings_E(...)
#define	Sq3StmtClearBindings_C(...)
#define	Sq3StmtExplain_E(...)
#define	Sq3StmtExplain_C(...)
#define	Sq3StmtReset_E(...)
#define	Sq3StmtReset_C(...)
#define	Sq3StmtStep_E(...)
#define	Sq3StmtStep_C(...)
#define	Sq3StmtStep_e(...)

Detailed Description

Sq3StmtC - various functions to perform misc operations …

Macro Definition Documentation

Sq3StmtClearBindings_C

#define Sq3StmtClearBindings_C

(

...

)

Value:

if (MkErrorCheckI(Sq3StmtClearBindings(__VA_ARGS__)))

Definition at line 632 of file sqlite3_overload_sq3.h.

Sq3StmtClearBindings_E

#define Sq3StmtClearBindings_E

(

...

)

Value:

MkErrorCheck(Sq3StmtClearBindings(__VA_ARGS__))

Definition at line 631 of file sqlite3_overload_sq3.h.

Sq3StmtExplain_C

#define Sq3StmtExplain_C

(

...

)

Value:

if (MkErrorCheckI(Sq3StmtExplain(__VA_ARGS__)))

Definition at line 634 of file sqlite3_overload_sq3.h.

Sq3StmtExplain_E

#define Sq3StmtExplain_E

(

...

)

Value:

MkErrorCheck(Sq3StmtExplain(__VA_ARGS__))

Definition at line 633 of file sqlite3_overload_sq3.h.

Sq3StmtNextStmt_1

#define Sq3StmtNextStmt_1

(

pDb

)

Value:

Sq3StmtNextStmt(pDb,NULL)

Definition at line 628 of file sqlite3_overload_sq3.h.

Sq3StmtReset_C

#define Sq3StmtReset_C

(

...

)

Value:

if (MkErrorCheckI(Sq3StmtReset(__VA_ARGS__)))

Definition at line 636 of file sqlite3_overload_sq3.h.

Sq3StmtReset_E

#define Sq3StmtReset_E

(

...

)

Value:

MkErrorCheck(Sq3StmtReset(__VA_ARGS__))

Definition at line 635 of file sqlite3_overload_sq3.h.

Sq3StmtStep_C

#define Sq3StmtStep_C

(

...

)

Value:

if (MkErrorCheckI(Sq3StmtStep(__VA_ARGS__)))

Definition at line 640 of file sqlite3_overload_sq3.h.

Sq3StmtStep_E

#define Sq3StmtStep_E

(

...

)

Value:

MkErrorCheck(Sq3StmtStep(__VA_ARGS__))

Definition at line 639 of file sqlite3_overload_sq3.h.

Sq3StmtStep_e

#define Sq3StmtStep_e

(

...

)

Value:

MK_EMBEDDED(enum Sq3ErrorE,Sq3StmtStep,__VA_ARGS__)

Definition at line 641 of file sqlite3_overload_sq3.h.

Function Documentation

Sq3StmtClearBindings()

static enum MkErrorE Sq3StmtClearBindings ( SQ3_STMT sq3stmt )

inlinestatic

Reset All Bindings On A Prepared Statement …

Contrary to the intuition of many, Sq3StmtReset () does not reset the bindings on a prepared statement. Use this routine to reset all host parameters to NULL.

Reference code from sqlite3:

SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);

Definition at line 370 of file Sq3StmtC_sq3.h.

                                                                  {
    SQ3_INSTANCE_HDL(sq3stmt);
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_clear_bindings(sq3stmt->nat);
    Sq3ErrorE_Check(sq3stmt, errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3StmtClearBindingsP()

enum MkErrorE Sq3StmtClearBindingsP

(

SQ3_STMT

sq3stmt

)

Non-inline replacement for Sq3StmtClearBindings …

Sq3StmtExplain()

static enum MkErrorE Sq3StmtExplain ( SQ3_STMT pStmt, MK_I32 eMode )

inlinestatic

Change The EXPLAIN Setting For A Prepared Statement …

The Sq3StmtExplain(S,E) interface changes the EXPLAIN setting for prepared statement S. If E is zero, then S becomes a normal prepared statement. If E is 1, then S behaves as if its SQL text began with "<a href="https://www.sqlite.org/lang_explain.html">EXPLAIN</a>". If E is 2, then S behaves as if its SQL text began with "<a href="https://www.sqlite.org/eqp.html">EXPLAIN QUERY PLAN</a>".

Calling Sq3StmtExplain(S,E) might cause S to be reprepared. SQLite tries to avoid a reprepare, but a reprepare might be necessary on the first transition into EXPLAIN or EXPLAIN QUERY PLAN mode.

Because of the potential need to reprepare, a call to Sq3StmtExplain(S,E) will fail with SQ3_RESULT_ERROR if S cannot be reprepared because it was created using sqlite3_prepare () instead of the newer Sq3StmtPrepareV2 () or Sq3StmtPrepareV3 () interfaces and hence has no saved SQL text with which to reprepare.

Changing the explain setting for a prepared statement does not change the original SQL text for the statement. Hence, if the SQL text originally began with EXPLAIN or EXPLAIN QUERY PLAN, but Sq3StmtExplain(S,0) is called to convert the statement into an ordinary statement, the EXPLAIN or EXPLAIN QUERY PLAN keywords will still appear in the Sq3StmtSql(S) output, even though the statement now acts like a normal SQL statement.

This routine returns SQ3_RESULT_OK if the explain mode is successfully changed, or an error code if the explain mode could not be changed. The explain mode cannot be changed while a statement is active. Hence, it is good practice to call Sq3StmtReset (S) immediately prior to calling Sq3StmtExplain(S,E).

Reference code from sqlite3:

SQLITE_API int sqlite3_stmt_explain(sqlite3_stmt *pStmt, int eMode);

Definition at line 380 of file Sq3StmtC_sq3.h.

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

Here is the caller graph for this function:

Sq3StmtExplainP()

enum MkErrorE Sq3StmtExplainP	(	SQ3_STMT	pStmt,
		MK_I32	eMode )

Non-inline replacement for Sq3StmtExplain …

Sq3StmtNextStmt()

static SQ3_STMT Sq3StmtNextStmt ( SQ3_LITE pDb, SQ3_STMT pStmt )

inlinestatic

Find the next prepared statement …

This interface returns a pointer to the next prepared statement after pStmt associated with the database connection pDb. If pStmt is NULL then this interface returns a pointer to the first prepared statement associated with the database connection pDb. If no prepared statement satisfies the conditions of this routine, it returns NULL.

The database connection pointer D in a call to Sq3StmtNextStmt (D,S) must refer to an open database connection and in particular must not be a NULL pointer.

Reference code from sqlite3:

SQLITE_API sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);

Definition at line 361 of file Sq3StmtC_sq3.h.

                                                                    {
    struct sqlite3 * pDb_hdl = pDb->nat;
    struct sqlite3_stmt * pStmt_hdl = pStmt->nat;
    return Sq3StmtC_ObjNew(sqlite3_next_stmt(pDb_hdl, pStmt_hdl));
  }

Here is the caller graph for this function:

Sq3StmtNextStmtP()

SQ3_STMT Sq3StmtNextStmtP	(	SQ3_LITE	pDb,
		SQ3_STMT	pStmt )

Non-inline replacement for Sq3StmtNextStmt …

Sq3StmtReset()

static enum MkErrorE Sq3StmtReset ( SQ3_STMT pStmt )

inlinestatic

Reset A Prepared Statement Object …

The Sq3StmtReset() function is called to reset a prepared statement object back to its initial state, ready to be re-executed. Any SQL statement variables that had values bound to them using the sqlite3_bind_*() API retain their values. Use Sq3StmtClearBindings () to reset the bindings.

The Sq3StmtReset (S) interface resets the prepared statement S back to the beginning of its program.

The return code from Sq3StmtReset (S) indicates whether or not the previous evaluation of prepared statement S completed successfully. If Sq3StmtStep (S) has never before been called on S or if Sq3StmtStep (S) has not been called since the previous call to Sq3StmtReset (S), then Sq3StmtReset (S) will return SQ3_RESULT_OK.

If the most recent call to Sq3StmtStep (S) for the prepared statement S indicated an error, then Sq3StmtReset (S) returns an appropriate error code. The Sq3StmtReset (S) interface might also return an error code if there were no prior errors but the process of resetting the prepared statement caused a new error. For example, if an INSERT statement with a RETURNING clause is only stepped one time, that one call to Sq3StmtStep (S) might return SQ3_RESULT_ROW but the overall statement might still fail and the Sq3StmtReset (S) call might return SQ3_RESULT_BUSY if locking constraints prevent the database change from committing. Therefore, it is important that applications check the return code from Sq3StmtReset (S) even if no prior call to Sq3StmtStep (S) indicated a problem.

The Sq3StmtReset (S) interface does not change the values of any bindings on the prepared statement S.

Reference code from sqlite3:

SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);

Definition at line 390 of file Sq3StmtC_sq3.h.

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

Here is the caller graph for this function:

Sq3StmtResetP()

enum MkErrorE Sq3StmtResetP

(

SQ3_STMT

pStmt

)

Non-inline replacement for Sq3StmtReset …

Sq3StmtStep()

static enum MkErrorE Sq3StmtStep ( SQ3_STMT sq3stmt, enum Sq3ErrorE * retCode )

inlinestatic

Evaluate An SQL Statement …

Parameters

[in]	sq3stmt	the Sq3StmtC instance to work on a statement
[out]	retCode	the return-code from the sqlite3_step command

Exceptions

MkExceptionC

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

After a prepared statement has been prepared using any of Sq3StmtPrepareV2 (), Sq3StmtPrepareV3 (), sqlite3_prepare16_v2 (), or sqlite3_prepare16_v3 () or one of the legacy interfaces sqlite3_prepare () or sqlite3_prepare16 (), this function must be called one or more times to evaluate the statement.

The details of the behavior of the Sq3StmtStep() interface depend on whether the statement was prepared using the newer "vX" interfaces Sq3StmtPrepareV3 (), Sq3StmtPrepareV2 (), sqlite3_prepare16_v3 (), sqlite3_prepare16_v2 () or the older legacy interfaces sqlite3_prepare () and sqlite3_prepare16 (). The use of the new "vX" interface is recommended for new applications but the legacy interface will continue to be supported.

In the legacy interface, the return value will be either SQ3_RESULT_BUSY, SQ3_RESULT_DONE, SQ3_RESULT_ROW, SQ3_RESULT_ERROR, or SQ3_RESULT_MISUSE. With the "v2" interface, any of the other result codes or extended result codes might be returned as well.

SQ3_RESULT_BUSY means that the database engine was unable to acquire the database locks it needs to do its job. If the statement is a COMMIT or occurs outside of an explicit transaction, then you can retry the statement. If the statement is not a COMMIT and occurs within an explicit transaction then you should rollback the transaction before continuing.

SQ3_RESULT_DONE means that the statement has finished executing successfully. Sq3StmtStep() should not be called again on this virtual machine without first calling Sq3StmtReset () to reset the virtual machine back to its initial state.

If the SQL statement being executed returns any data, then SQ3_RESULT_ROW is returned each time a new row of data is ready for processing by the caller. The values may be accessed using the column access functions. Sq3StmtStep() is called again to retrieve the next row of data.

SQ3_RESULT_ERROR means that a run-time error (such as a constraint violation) has occurred. Sq3StmtStep() should not be called again on the VM. More information may be found by calling Sq3LiteErrMsg (). With the legacy interface, a more specific error code (for example, SQ3_RESULT_INTERRUPT, SQ3_RESULT_SCHEMA, SQ3_RESULT_CORRUPT, and so forth) can be obtained by calling Sq3StmtReset () on the prepared statement. In the "v2" interface, the more specific error code is returned directly by Sq3StmtStep().

SQ3_RESULT_MISUSE means that the this routine was called inappropriately. Perhaps it was called on a prepared statement that has already been finalized or on one that had previously returned SQ3_RESULT_ERROR or SQ3_RESULT_DONE. Or it could be the case that the same database connection is being used by two or more threads at the same moment in time.

For all versions of SQLite up to and including 3.6.23.1, a call to Sq3StmtReset () was required after Sq3StmtStep() returned anything other than SQ3_RESULT_ROW before any subsequent invocation of Sq3StmtStep(). Failure to reset the prepared statement using Sq3StmtReset () would result in an SQ3_RESULT_MISUSE return from Sq3StmtStep(). But after version 3.6.23.1 (dateof:3.6.23.1, Sq3StmtStep() began calling Sq3StmtReset () automatically in this circumstance rather than returning SQ3_RESULT_MISUSE. This is not considered a compatibility break because any application that ever receives an SQ3_RESULT_MISUSE error is broken by definition. The SQLITE_OMIT_AUTORESET compile-time option can be used to restore the legacy behavior.

Goofy Interface Alert: In the legacy interface, the Sq3StmtStep() API always returns a generic error code, SQ3_RESULT_ERROR, following any error other than SQ3_RESULT_BUSY and SQ3_RESULT_MISUSE. You must call Sq3StmtReset () or Sq3StmtFinalize () in order to find one of the specific error codes that better describes the error. We admit that this is a goofy design. The problem has been fixed with the "v2" interface. If you prepare all of your SQL statements using Sq3StmtPrepareV3 () or Sq3StmtPrepareV2 () or sqlite3_prepare16_v2 () or sqlite3_prepare16_v3 () instead of the legacy sqlite3_prepare () and sqlite3_prepare16 () interfaces, then the more specific error codes are returned directly by Sq3StmtStep(). The use of the "vX" interfaces is recommended.

Reference code from sqlite3:

SQLITE_API int sqlite3_step(sqlite3_stmt*);

Definition at line 700 of file Sq3StmtC_sq3.h.

                                                                                {
  SQ3_INSTANCE_HDL(sq3stmt);
  enum Sq3ErrorE errVal = *retCode = (enum Sq3ErrorE)sqlite3_step(sq3stmt->nat);
  Sq3ErrorE_Check(sq3stmt, errVal);
  
  return MK_OK;
error:
  return MK_ERROR;
} 

Here is the caller graph for this function:

Sq3StmtStepP()

enum MkErrorE Sq3StmtStepP	(	SQ3_STMT	sq3stmt,
		enum Sq3ErrorE *	retCode )

Non-inline replacement for Sq3StmtStep …