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__)))

Sq3LiteExec

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 …

Definition Sq3LiteC_sq3.h:255

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__)

MK_RT_CALL

#define MK_RT_CALL

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(),...

Definition at line 393 of file sqlite3_overload_sq3.h.

◆ Sq3LiteExecV2_C

#define Sq3LiteExecV2_C ( ... )

Value:

if (MkErrorCheckI(Sq3LiteExecV2(__VA_ARGS__)))

Sq3LiteExecV2

#define Sq3LiteExecV2(...)

Definition sqlite3_overload_sq3.h:393

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__)

MK_RT_CALL_NULL

#define MK_RT_CALL_NULL

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__)))

Sq3LiteSleep

static enum MkErrorE Sq3LiteSleep(MK_I32 arg0)

Suspend Execution For A Short Time …

Definition Sq3LiteC_sq3.h:267

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 …

Sq3LiteExec : callback signature: callback-args := vals:List[in] , cols:List[in]

[static] def callback ( callback-args )

[instance] class YYY:

def callback ( self, callback-args )

[class] class ZZZ:

@staticmethod

def callback ( callback-args )

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

Sq3LiteExec : callback example

  # RPC example for a callback SINGELTON to provide a callback with ARRAY-of-STRING as argument
  class LibSq3LiteRpcServerExecIF:

    # constructer define local attributes
    def __init__ (self):
      self.valL = MkBufferListC()
      self.colL = MkBufferListC()
      #required to collect **all** result-set into **one** object
      self.bus  = MkBufferStreamC()
    
    # "set" method initialize the SINGELTON callback data
    def set (self, rpc, cfc):
      self.rpc = rpc
      self.cfc = cfc

      self.bus.Reset()
      # "cfc" determines which type of callback is used
      match cfc:
        case 0: return  None
        case 1: return  self.callback1
        case 2: return  self.callback2

      MkErrorC.DEFAULT().SetC(f"invalid control number '{cfc}', expect: 0,1,2")

    def getBUS (self):
      self.bus

    def _init (self, vals, cols):
      self.valL.Reset().AppendLA(vals)
      self.colL.Reset().AppendLA(cols)

    # "Callback" to collect **all** result sets into **one** MkBufferStreamC data object 
    # which is then sent to the client at the end with **one** response.
    def callback1 (self, vals, cols):
      self._init(vals,cols)

      self.bus.WriteBFL(self.valL)
      self.bus.WriteBFL(self.colL)

    # "Callback" to send each result set **individually** to the client
    def callback2 (self, vals, cols):
      self._init(vals,cols)

      self.rpc.SendSTART()
      self.rpc.SendBFL(self.valL)
      self.rpc.SendBFL(self.colL)
      self.rpc.SendRETURN_SUB()

  # RPC callback called from service
  def Sq3LiteExec (self):
    # create one THREAD-LOCAL callback instance as storage for additional attributes
    if not hasattr(self,"Sq3LiteExecData"):
      self.Sq3LiteExecData = self.LibSq3LiteRpcServerExecIF()

    # collect service data
    sq3lite = self.ReadRpcHDL(Sq3LiteC)
    sql     = self.ReadSTR()
    cfc     = self.ReadI32()

    # initialize the "Sq3LiteExecData", set the "Callback" and start the "sql" query with "Exec"
    sq3lite.Exec(sql, self.Sq3LiteExecData.set(self, cfc))

    # if "callback2" was used, return the MkBufferStreamC data object
    if self.ServiceIsTransaction():
      if cfc == 1:
        self.SendSTART()
        self.SendBUS_FLAT(self.Sq3LiteExecData.bus)
      self.SendRETURN()

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;
  }

Here is the caller graph for this function:

◆ 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.

Exceptions

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

Sq3LiteExecV2 : callback signature: callback-args := vals:MkBufferList[in] , cols:MkBufferList[in]

[static] def callback ( callback-args )

[instance] class YYY:

def callback ( self, callback-args )

[class] class ZZZ:

@staticmethod

def callback ( callback-args )

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
  class LibSq3LiteRpcServerExecV2IF:

    # constructer define local attributes
    def __init__ (self):
      #required to collect **all** result-set into **one** object
      self.bus  = MkBufferStreamC()
    
    # "set" method initialize the SINGELTON callback data
    def set (self, rpc, cfc):
      self.rpc = rpc

      self.bus.Reset()
      # "cfc" determines which type of callback is used
      match cfc:
        case 0: return  None
        case 1: return  self.callback1
        case 2: return  self.callback2

      MkErrorC.DEFAULT().SetC(f"invalid control number '{cfc}', expect: 0,1,2")

    def getBUS (self):
      self.bus

    # "Callback" to collect **all** result sets into **one** MkBufferStreamC data object 
    # which is then sent to the client at the end with **one** response.
    def callback1 (self, vals, cols):
      self.bus.WriteBFL(vals)
      self.bus.WriteBFL(cols)

    # "Callback" to send each result-set **individually** to the client
    def callback2 (self, vals, cols):
      self.rpc.SendSTART()
      self.rpc.SendBFL(vals)
      self.rpc.SendBFL(cols)
      self.rpc.SendRETURN_SUB()

  # RPC callback called from service
  def Sq3LiteExecV2 (self):
    # create one THREAD-LOCAL callback instance as storage for additional attributes
    if not hasattr(self,"Sq3LiteExecV2Data"):
      self.Sq3LiteExecV2Data = self.LibSq3LiteRpcServerExecV2IF()

    # collect service data
    sq3lite = self.ReadRpcHDL(Sq3LiteC)
    sql     = self.ReadSTR()
    cfc     = self.ReadI32()

    # initialize the "Sq3LiteExecV2Data", set the "Callback" and start the "sql" query with "ExecV2"
    sq3lite.ExecV2(sql, self.Sq3LiteExecV2Data.set(self, cfc))

    # if "callback2" was used, return the MkBufferStreamC data object
    if self.ServiceIsTransaction():
      if cfc == 1:
        self.SendSTART()
        self.SendBUS_FLAT(self.Sq3LiteExecV2Data.bus)
      self.SendRETURN()

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);

sqlite3_sleep

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;
  }

Here is the caller graph for this function:

◆ Sq3LiteSleepP()

enum MkErrorE Sq3LiteSleepP ( MK_I32 arg0 )

Non-inline replacement for Sq3LiteSleep …

Macros

Typedefs

Functions

Sq3LiteC - Sq3LiteC_Execution_C_API - function

Sq3LiteC - Sq3LiteC_Execution_C_API - overload

Detailed Description

Macro Definition Documentation

◆ Sq3Fupu_Sq3LiteExec_callback_call_args

◆ Sq3Fupu_Sq3LiteExec_callback_call_check

◆ Sq3Fupu_Sq3LiteExec_callback_call_ret

◆ Sq3Fupu_Sq3LiteExecV2CB_callback_call_check

◆ Sq3LiteExec_C

◆ Sq3LiteExec_E

◆ Sq3LiteExecV2

◆ Sq3LiteExecV2_C

◆ Sq3LiteExecV2_E

◆ Sq3LiteExecV2_NULL

◆ Sq3LiteExecV2CB_args

◆ Sq3LiteExecV2CB_ret

◆ Sq3LiteSleep_C

◆ Sq3LiteSleep_E

Typedef Documentation

◆ Sq3Fupu_Sq3LiteExec_callback_call

◆ Sq3LiteExecV2CB

Function Documentation

◆ Sq3LiteExec()

sqlite3_exec documentation

◆ Sq3LiteExecP()

◆ Sq3LiteExecV2_RT()

◆ Sq3LiteSleep()

◆ Sq3LiteSleepP()