Sq3LiteC_Execution_C_API

Sq3LiteC - execute a sql statement … More...

Collaboration diagram for Sq3LiteC_Execution_C_API:

Macros
#define	Sq3Fupu_Sq3LiteExec_callback_call_ret   MK_I32
#define	Sq3Fupu_Sq3LiteExec_callback_call_args   MK_CBP callV1, MK_I32 num, MK_STR *vals, MK_STR *cols
#define	Sq3Fupu_Sq3LiteExec_callback_call_check
#define	Sq3Fupu_Sq3LiteExecV2CB_callback_call_check
#define	Sq3LiteExecV2CB_ret   enum MkErrorE
#define	Sq3LiteExecV2CB_args   MK_RT_ARGS MK_CBP callV2, MK_BFL vals, MK_BFL cols

Typedefs
typedef Sq3Fupu_Sq3LiteExec_callback_call_ret(*	Sq3Fupu_Sq3LiteExec_callback_call) (Sq3Fupu_Sq3LiteExec_callback_call_args)
typedef enum MkErrorE(*	Sq3LiteExecV2CB) (MK_RT mkrt, MK_CBP callV2, MK_BFL vals, MK_BFL cols)
	callback for Sq3LiteExecV2

Functions
static enum MkErrorE	Sq3LiteExec (SQ3_LITE sq3lite, MK_STRN sql, Sq3Fupu_Sq3LiteExec_callback_call callback_call, MK_CBP callback_data)
	One-Step Query Execution Interface …
static enum MkErrorE	Sq3LiteSleep (MK_I32 arg0)
	Suspend Execution For A Short Time …
enum MkErrorE	Sq3LiteExecV2_RT (MK_RT mkrt, SQ3_LITE sq3lite, MK_STRN sql, Sq3LiteExecV2CB callback_call, MK_CBP callback)
	The Sq3LiteExecV2() interface is a convenience wrapper around Sq3StmtPrepareV2(), Sq3StmtStep(), and Sq3StmtFinalize(), that allows an application to run multiple statements of SQL without having to use a lot of C code.

Sq3LiteC - Sq3LiteC_Execution_C_API - function
enum MkErrorE	Sq3LiteExecP (SQ3_LITE sq3lite, MK_STRN sql, Sq3Fupu_Sq3LiteExec_callback_call callback_call, MK_CBP callback_data)
	Non-inline replacement for Sq3LiteExec …
enum MkErrorE	Sq3LiteSleepP (MK_I32 arg0)
	Non-inline replacement for Sq3LiteSleep …

Sq3LiteC - Sq3LiteC_Execution_C_API - overload
#define	Sq3LiteExec_E(...)
#define	Sq3LiteExec_C(...)
#define	Sq3LiteExecV2_NULL(...)
#define	Sq3LiteExecV2(...)
#define	Sq3LiteExecV2_E(...)
#define	Sq3LiteExecV2_C(...)
#define	Sq3LiteSleep_E(...)
#define	Sq3LiteSleep_C(...)

Detailed Description

Sq3LiteC - execute a sql statement …

Macro Definition Documentation

Sq3Fupu_Sq3LiteExec_callback_call_args

#define Sq3Fupu_Sq3LiteExec_callback_call_args   MK_CBP callV1, MK_I32 num, MK_STR *vals, MK_STR *cols

Definition at line 89 of file Sq3LiteC_sq3.h.

Sq3Fupu_Sq3LiteExec_callback_call_check

#define Sq3Fupu_Sq3LiteExec_callback_call_check

Value:

  do { \
  assert(callV1 != NULL); \
} while (0)

Definition at line 725 of file Sq3LiteC_sq3.h.

#define Sq3Fupu_Sq3LiteExec_callback_call_check do { \
  assert(callV1 != NULL); \
} while (0)

Sq3Fupu_Sq3LiteExec_callback_call_ret

#define Sq3Fupu_Sq3LiteExec_callback_call_ret   MK_I32

Definition at line 88 of file Sq3LiteC_sq3.h.

Sq3Fupu_Sq3LiteExecV2CB_callback_call_check

#define Sq3Fupu_Sq3LiteExecV2CB_callback_call_check

Value:

  do { \
  assert(callV2 != NULL); \
} while (0)

Definition at line 729 of file Sq3LiteC_sq3.h.

#define Sq3Fupu_Sq3LiteExecV2CB_callback_call_check do { \
  assert(callV2 != NULL); \
} while (0)

Sq3LiteExec_C

#define Sq3LiteExec_C

(

...

)

Value:

if (MkErrorCheckI(Sq3LiteExec(__VA_ARGS__)))

Definition at line 391 of file sqlite3_overload_sq3.h.

Sq3LiteExec_E

#define Sq3LiteExec_E

(

...

)

Value:

MkErrorCheck(Sq3LiteExec(__VA_ARGS__))

Definition at line 390 of file sqlite3_overload_sq3.h.

Sq3LiteExecV2

#define Sq3LiteExecV2

(

...

)

Value:

Sq3LiteExecV2_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 393 of file sqlite3_overload_sq3.h.

Sq3LiteExecV2_C

#define Sq3LiteExecV2_C

(

...

)

Value:

if (MkErrorCheckI(Sq3LiteExecV2(__VA_ARGS__)))

Definition at line 395 of file sqlite3_overload_sq3.h.

Sq3LiteExecV2_E

#define Sq3LiteExecV2_E

(

...

)

Value:

MkErrorCheck(Sq3LiteExecV2(__VA_ARGS__))

Definition at line 394 of file sqlite3_overload_sq3.h.

Sq3LiteExecV2_NULL

#define Sq3LiteExecV2_NULL

(

...

)

Value:

Sq3LiteExecV2_RT(MK_RT_CALL_NULL __VA_ARGS__)

Definition at line 392 of file sqlite3_overload_sq3.h.

Sq3LiteExecV2CB_args

#define Sq3LiteExecV2CB_args   MK_RT_ARGS MK_CBP callV2, MK_BFL vals, MK_BFL cols

Definition at line 735 of file Sq3LiteC_sq3.h.

Sq3LiteExecV2CB_ret

#define Sq3LiteExecV2CB_ret   enum MkErrorE

Definition at line 734 of file Sq3LiteC_sq3.h.

Sq3LiteSleep_C

#define Sq3LiteSleep_C

(

...

)

Value:

if (MkErrorCheckI(Sq3LiteSleep(__VA_ARGS__)))

Definition at line 399 of file sqlite3_overload_sq3.h.

Sq3LiteSleep_E

#define Sq3LiteSleep_E

(

...

)

Value:

MkErrorCheck(Sq3LiteSleep(__VA_ARGS__))

Definition at line 398 of file sqlite3_overload_sq3.h.

Typedef Documentation

Sq3Fupu_Sq3LiteExec_callback_call

typedef Sq3Fupu_Sq3LiteExec_callback_call_ret(* Sq3Fupu_Sq3LiteExec_callback_call) (Sq3Fupu_Sq3LiteExec_callback_call_args)

Definition at line 90 of file Sq3LiteC_sq3.h.

Sq3LiteExecV2CB

typedef enum MkErrorE(* Sq3LiteExecV2CB) (MK_RT mkrt,MK_CBP callV2, MK_BFL vals, MK_BFL cols)

callback for Sq3LiteExecV2

Parameters

[in]	callV2	Additional data from the 4'th argument of Sq3LiteExecV2
[in]	vals	The values returned
[in]	cols	The column-names from the values returned

Returns

The MkErrorE with non MK_ERROR signal ok (continue) or MK_ERROR signal error (abort)

Definition at line 707 of file Sq3LiteC_sq3.h.

Function Documentation

Sq3LiteExec()

static enum MkErrorE Sq3LiteExec ( SQ3_LITE sq3lite, MK_STRN sql, Sq3Fupu_Sq3LiteExec_callback_call callback_call, MK_CBP callback_data )

inlinestatic

One-Step Query Execution Interface …

Parameters

[in]	sq3lite	the Sq3LiteC instance to work on a database
[in]	sql	The sql data to be processed
[in]	callback_call	(C-only) The callback to call from type Sq3LiteExecV2CB
[in]	callback_data	The additional data, used as Sq3LiteExecV2CB first argument and as callback for a non-C language.

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk (C-only)

Sq3LiteExec : callback signature

    #define Sq3Fupu_Sq3LiteExec_callback_call_ret  MK_I32
    #define Sq3Fupu_Sq3LiteExec_callback_call_args MK_CBP callV1, MK_I32 num, MK_STR *vals, MK_STR *cols
    typedef Sq3Fupu_Sq3LiteExec_callback_call_ret (*Sq3Fupu_Sq3LiteExec_callback_call) (Sq3Fupu_Sq3LiteExec_callback_call_args);

The callback Sq3Fupu_Sq3LiteExec_callback_call has the same signature as the sqlite3_exec callback.

Read more about how to define a service-callback in theLink .

Note

For the C-language the callback_call is the function called and the callback_data is the additional data. This is different for the non-C-languges from (C,C++,C#,VB.NET,Java,Python,Ruby,Perl,PHP,Tcl or GO).

For the non-C-language the callback_call is internal and the callback_data is the target-language-callback.

Sq3LiteExec : callback example

// RPC example for a callback SINGELTON to provide a callback with ARRAY-of-STRING as argument
static Sq3Fupu_Sq3LiteExec_callback_call_ret Sq3LiteExecCB (Sq3Fupu_Sq3LiteExec_callback_call_args)
{
  // constructer define local attributes
  const struct Sq3CbS * cbP = (struct Sq3CbS *) callV1;
  MkRtSetup_RT(cbP->mkrt);

  const MQ_CTX rpc = cbP->rpc;
  if (cbP->ret == NULL) {   // callback_first_check == 2
    // "Callback1" to collect **all** result sets into **one** MkBufferStreamC data object 
    // which is then sent to the client at the end with **one** response.
    MqSendSTART_E(rpc);
    MqSendBFL_E(rpc, MkBufferListCreateVC(num,(MK_STRN*)vals));
    MqSendBFL_E(rpc, MkBufferListCreateVC(num,(MK_STRN*)cols));
    MqSendRETURN_SUB(rpc);
  } else {                  // callback_first_check == 1
    // "Callback2" to send each result set **individually** to the client
    MkBufferStreamReset(cbP->ret);
    MkBufferStreamWriteBFL_E(cbP->ret, MkBufferListCreateVC(num,(MK_STRN*)vals));
    MkBufferStreamWriteBFL_E(cbP->ret, MkBufferListCreateVC(num,(MK_STRN*)cols));
  }
  return 0;
error:
  MkErrorStack_1X(rpc);
  return 1;
}

#define rpc mqctx   // naming in MQ_SERVICE_CALL_ARGS

// RPC callback called from service
static enum MkErrorE SrvSq3LiteExec ( MQ_SERVICE_CALL_ARGS )
{
  // create one THREAD-LOCAL callback instance as storage for additional attributes
  MkBufferStreamCreateTLS_T(MkBufferStream256C,bus);

  // collect service data
  SQ3_LITE sq3lite = Sq3LiteHandleResolve_e(MqReadHDL_e(rpc));
  MK_STRN sql = MqReadSTR_e(rpc);
  const MK_I32 callback_first_check = MqReadI32_e(rpc);
  Sq3Fupu_Sq3LiteExec_callback_call callback = NULL;
  MK_CBP callback_first_ptr = NULL;

  // initialize the "Sq3LiteExecData", set the "Callback"
  switch (callback_first_check) {
    case 0:
      callback = NULL;
      callback_first_ptr = NULL;
      break;
    case 1: {
      callback = Sq3LiteExecCB;
      struct Sq3CbS Sq3CbS_callback_first_ptr = {MK_RT_PTR,rpc,bus};
      callback_first_ptr = &Sq3CbS_callback_first_ptr;
      break;
    }
    case 2: {
      callback = Sq3LiteExecCB;
      struct Sq3CbS Sq3CbS_callback_first_ptr = {MK_RT_PTR,rpc,NULL};
      callback_first_ptr = &Sq3CbS_callback_first_ptr;
      break;
    }
    default: {
      return MkErrorSetV_1E("invalid control number '%d', expect: 1,2,3", callback_first_check);
    }
  }

  // start the "sql" query with "Exec"
  Sq3LiteExec_E(sq3lite, sql, callback, callback_first_ptr);

  // if "Callback2" was used, return the MkBufferStreamC data object
  MqSendSTART_E(rpc);
  switch (callback_first_check) {
    case 1:
      MqSendBUS_FLAT_E(rpc,bus);
      break;
  }
error:
  return MqSendRETURN(rpc);
}
#undef rpc

sqlite3_exec : documentation

The Sq3LiteExec() interface is a convenience wrapper around Sq3StmtPrepareV2 (), Sq3StmtStep (), and Sq3StmtFinalize (), that allows an application to run multiple statements of SQL without having to use a lot of C code.

The Sq3LiteExec() interface runs zero or more UTF-8 encoded, semicolon-separate SQL statements passed into its 2nd argument, in the context of the database connection passed in as its 1st argument. If the callback function of the 3rd argument to Sq3LiteExec() is not NULL, then it is invoked for each result row coming out of the evaluated SQL statements. The 4th argument to Sq3LiteExec() is relayed through to the 1st argument of each callback invocation. If the callback pointer to Sq3LiteExec() is NULL, then no callback is ever invoked and result rows are ignored.

If an error occurs while evaluating the SQL statements passed into Sq3LiteExec(), then execution of the current statement stops and subsequent statements are skipped. If the 5th parameter to Sq3LiteExec() is not NULL then any error message is written into memory obtained from Sq3Malloc () and passed back through the 5th parameter. To avoid memory leaks, the application should invoke Sq3Free () on error message strings returned through the 5th parameter of Sq3LiteExec() after the error message string is no longer needed. If the 5th parameter to Sq3LiteExec() is not NULL and no errors occur, then Sq3LiteExec() sets the pointer in its 5th parameter to NULL before returning.

If an Sq3LiteExec() callback returns non-zero, the Sq3LiteExec() routine returns SQ3_RESULT_ABORT without invoking the callback again and without running any subsequent SQL statements.

The 2nd argument to the Sq3LiteExec() callback function is the number of columns in the result. The 3rd argument to the Sq3LiteExec() callback is an array of pointers to strings obtained as if from Sq3StmtColumnText (), one for each column. If an element of a result row is NULL then the corresponding string pointer for the Sq3LiteExec() callback is a NULL pointer. The 4th argument to the Sq3LiteExec() callback is an array of pointers to strings where each entry represents the name of corresponding result column as obtained from Sq3StmtColumnName ().

If the 2nd parameter to Sq3LiteExec() is a NULL pointer, a pointer to an empty string, or a pointer that contains only whitespace and/or SQL comments, then no SQL statements are evaluated and the database is not changed.

Restrictions:

• The application must ensure that the 1st parameter to Sq3LiteExec() is a valid and open database connection.
• The application must not close the database connection specified by the 1st parameter to Sq3LiteExec() while Sq3LiteExec() is running.
• The application must not modify the SQL statement text passed into the 2nd parameter of Sq3LiteExec() while Sq3LiteExec() is running.

Reference code from sqlite3:

SQLITE_API int sqlite3_exec(
  sqlite3*,                                  // An open database 
  const char *sql,                           // SQL to be evaluated 
  int (*callback)(void*,int,char**,char**),  // Callback function 
  void *,                                    // 1st argument to callback 
  char **errmsg                              // Error msg written here 
);

Definition at line 255 of file Sq3LiteC_sq3.h.

                                                                                                                                             {
    SQ3_INSTANCE_HDL(sq3lite);
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_exec(sq3lite->nat, sql, callback_call, callback_data, NULL);
    Sq3ErrorE_Check(sq3lite, errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Sq3LiteExecP()

enum MkErrorE Sq3LiteExecP	(	SQ3_LITE	sq3lite,
		MK_STRN	sql,
		Sq3Fupu_Sq3LiteExec_callback_call	callback_call,
		MK_CBP	callback_data )

Non-inline replacement for Sq3LiteExec …

Sq3LiteExecV2_RT()

enum MkErrorE Sq3LiteExecV2_RT	(	MK_RT	mkrt,
		SQ3_LITE	sq3lite,
		MK_STRN	sql,
		Sq3LiteExecV2CB	callback_call,
		MK_CBP	callback )

The Sq3LiteExecV2() interface is a convenience wrapper around Sq3StmtPrepareV2(), Sq3StmtStep(), and Sq3StmtFinalize(), that allows an application to run multiple statements of SQL without having to use a lot of C code.

This is an enhanced version of Sq3LiteExec with support of MkBufferListC data-type for the vals and cols arguments.

Parameters

[in]	mkrt	the MkRuntimeS instance to work on - the runtime argument, used by MK_RT_CALL (C-only)
[in]	sq3lite	the Sq3LiteC instance to work on a database
[in]	sql	The sql data to be processed
[in]	callback_call	(C-only) The callback to call from type Sq3LiteExecV2CB
[in]	callback	The additional data, used as Sq3LiteExecV2CB first argument and as callback for a non-C language.

Returns

The MkErrorE status from the DEFAULT MkErrorC in MkRuntimeS::error_mk

Sq3LiteExecV2 : callback signature

#define Sq3LiteExecV2CB_ret   enum MkErrorE
#define Sq3LiteExecV2CB_args  MK_RT_ARGS MK_CBP callV2, MK_BFL vals, MK_BFL cols
typedef enum MkErrorE (*Sq3LiteExecV2CB) (MK_RT_ARGS MK_CBP callV2, MK_BFL vals, MK_BFL cols);

Read more about how to define a service-callback in theLink .

Sq3LiteExecV2 : callback example

// RPC example for a callback SINGELTON to provide a callback with MkBufferListC as argument
static Sq3LiteExecV2CB_ret mySq3LiteExecV2CB (Sq3LiteExecV2CB_args)
{
  // constructer define local attributes
  const struct Sq3CbS * cbP = (struct Sq3CbS *) callV2;
  const MQ_CTX rpc = cbP->rpc;

  if (cbP->ret == NULL) {   // callback_first_check == 2
    // "Callback1" to collect **all** result sets into **one** MkBufferStreamC data object 
    // which is then sent to the client at the end with **one** response.
    MqSendSTART_E(rpc);
    MqSendBFL_E(rpc, vals);
    MqSendBFL_E(rpc, cols);
    MqSendRETURN_SUB(rpc);
  } else {                  // callback_first_check == 1
    // "Callback2" to send each result-set **individually** to the client
    MkBufferStreamReset(cbP->ret);
    MkBufferStreamWriteBFL_E(cbP->ret, vals);
    MkBufferStreamWriteBFL_E(cbP->ret, cols);
  }
  return 0;
error:
  MkErrorStack_1X(rpc);
  return 1;
}

#define rpc mqctx   // naming in MQ_SERVICE_CALL_ARGS

// RPC callback called from service
static enum MkErrorE SrvSq3LiteExecV2 ( MQ_SERVICE_CALL_ARGS )
{
  // create one THREAD-LOCAL callback instance as storage for additional attributes
  MkBufferStreamCreateTLS_T(MkBufferStream256C,bus);

  // collect service data
  SQ3_LITE sq3lite = Sq3LiteHandleResolve_e(MqReadHDL_e(rpc));
  MK_STRN sql = MqReadSTR_e(rpc);
  const MK_I32 callback_first_check = MqReadI32_e(rpc);
  Sq3LiteExecV2CB callback = NULL;
  MK_CBP callback_first_ptr = NULL;

  // initialize the "Sq3LiteExecData", set the "Callback"
  switch (callback_first_check) {
    case 0:
      callback = NULL;
      callback_first_ptr = NULL;
      break;
    case 1: {
      callback = mySq3LiteExecV2CB;
      struct Sq3CbS Sq3CbS_callback_first_ptr = {MK_RT_PTR,rpc,bus};
      callback_first_ptr = &Sq3CbS_callback_first_ptr;
      break;
    }
    case 2: {
      callback = mySq3LiteExecV2CB;
      struct Sq3CbS Sq3CbS_callback_first_ptr = {MK_RT_PTR,rpc,NULL};
      callback_first_ptr = &Sq3CbS_callback_first_ptr;
      break;
    }
    default: {
      return MkErrorSetV_1E("invalid control number '%d', expect: 1,2,3", callback_first_check);
    }
  }

  // start the "sql" query with "ExecV2"
  Sq3LiteExecV2_E(sq3lite, sql, callback, callback_first_ptr);

  // if "Callback2" was used, return the MkBufferStreamC data object
  MqSendSTART_E(rpc);
  switch (callback_first_check) {
    case 1:
      MqSendBUS_FLAT_E(rpc,bus);
      break;
  }
error:
  return MqSendRETURN(rpc);
}
#undef rpc

Sq3LiteExec : documentation

read more at: Sq3LiteExec

Sq3LiteSleep()

static enum MkErrorE Sq3LiteSleep ( MK_I32 arg0 )

inlinestatic

Suspend Execution For A Short Time …

The Sq3LiteSleep() function causes the current thread to suspend execution for at least a number of milliseconds specified in its parameter.

If the operating system does not support sleep requests with millisecond time resolution, then the time will be rounded up to the nearest second. The number of milliseconds of sleep actually requested from the operating system is returned.

SQLite implements this interface by calling the xSleep() method of the default sqlite3_vfs object. If the xSleep() method of the default VFS is not implemented correctly, or not implemented at all, then the behavior of Sq3LiteSleep() may deviate from the description in the previous paragraphs.

If a negative argument is passed to Sq3LiteSleep() the results vary by VFS and operating system. Some system treat a negative argument as an instruction to sleep forever. Others understand it to mean do not sleep at all. In SQLite version 3.42.0 and later, a negative argument passed into Sq3LiteSleep() is changed to zero before it is relayed down into the xSleep method of the VFS.

Reference code from sqlite3:

SQLITE_API int sqlite3_sleep(int);

Definition at line 267 of file Sq3LiteC_sq3.h.

                                                     {
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_sleep(arg0);
    Sq3ErrorE_Check_Static(Sq3LiteC_TT,errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Sq3LiteSleepP()

enum MkErrorE Sq3LiteSleepP

(

MK_I32

arg0

)

Non-inline replacement for Sq3LiteSleep …