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 …

Sq3LiteExec : callback signature

  callback-args := vals:List[in] cols:List[in]
  [static]   proc callback { callback-args ?additional-args...? } ...
  [instance] ::oo::class create YYY {
               method callback { callback-args ?additional-args...? } ...
  [class]    ::oo::class create ZZZ {
               self method callback { callback-args ?additional-args...? } ...

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

Sq3LiteExec : callback example with tcl proc interface

proc myCb {vals cols arg1 arg2 ...} {
  ...
}
...
db Exec "sql..." [list myCb arg1 arg2 ...]

Sq3LiteExec : callback example with tcl OO interface

# RPC example for a callback SINGELTON to provide a callback with ARRAY-of-STRING as argument
oo::class create LibSq3LiteRpcServerExecIF {
  variable rpc cfc

  # constructer define local attributes
  constructor {} {
    MkBufferListC   create valL
    MkBufferListC   create colL
    MkBufferStreamC create bus
  }
  
  # "set" method initialize the SINGELTON callback data
  method set {myRpc myCfc} {

    set rpc $myRpc
    set cfc $myCfc
    bus Reset

    # "cfc" determines which type of callback is used
    switch $cfc {
      0 { return  MK_NULL }
      1 { return  [list [self] callback1] }
      2 { return  [list [self] callback2] }
    }
    [MkErrorC DEFAULT] SetC "invalid control number '$cfc', expect: 0,1,2"
  }

  method getBUS {} {
    namespace origin bus
  }

  method _init {vals cols} {
    [valL Reset] AppendLA $vals
    [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.
  method callback1 {vals cols} {
    my _init $vals $cols

    bus WriteBFL valL
    bus WriteBFL colL
  }

  # "Callback" to send each result set **individually** to the client
  method callback2 {vals cols} {
    my _init $vals $cols

    $rpc SendSTART
    $rpc SendBFL valL
    $rpc SendBFL colL
    $rpc SendRETURN_SUB
  }
}

# RPC callback called from service
oo::define LibSq3LiteRpcServer method Sq3LiteExec {} {
  # create one THREAD-LOCAL callback instance as storage for additional attributes
  if {![info object isa object Sq3LiteExecData]} {
    LibSq3LiteRpcServerExecIF create Sq3LiteExecData
  }

  set sq3lite [my Sq3LiteC_RpcRead]
  set sql     [my ReadSTR]
  set cfc     [my ReadI32]

  # initialize the "Sq3LiteExecData", set the "Callback" and start the "sql" query with "Exec"
  $sq3lite Exec $sql [Sq3LiteExecData set [self] $cfc]

  # if "callback2" was used, return the MkBufferStreamC data object
  if {[my ServiceIsTransaction]} {
    if {$cfc == 1} {
      my SendSTART
      my SendBUS_FLAT [Sq3LiteExecData getBUS]
    }
    my 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]   proc callback { callback-args ?additional-args...? } ...
  [instance] ::oo::class create YYY {
               method callback { callback-args ?additional-args...? } ...
  [class]    ::oo::class create ZZZ {
               self method callback { callback-args ?additional-args...? } ...

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

Sq3LiteExecV2 : callback example with tcl proc interface

The "callback" "myCb" is defined as a "proc" or as a "method", the "method" require the "object" first.

proc myCb {vals cols arg1 arg2 ...} {
  ...
}

The "callback" is added as a list starting with the proc "myCb" followed by additional arguments :

db ExecV2 "sql..." [list myCb arg1 arg2 ...]

Sq3LiteExecV2 : callback example with tcl OO interface

# RPC example for a callback SINGELTON to provide a callback with MkBufferListC as argument
oo::class create LibSq3LiteRpcServerExecV2IF {
  variable rpc

  # constructer define local attributes
  constructor {} {
    MkBufferStreamC create bus
  }
  
  # "set" method initialize the SINGELTON callback data
  method set {myRpc cfc} {
    set rpc $myRpc
    bus Reset
    # "cfc" determines which type of callback is used
    switch $cfc {
      0 { return  MK_NULL }
      1 { return  [list [self] callback1] }
      2 { return  [list [self] callback2] }
    }
    [MkErrorC FORMAT] SetC "invalid control number '$cfc', expect: 0,1,2"
  }

  method getBUS {} {
    namespace origin 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.
  method callback1 {valL colL} {
    bus WriteBFL $valL
    bus WriteBFL $colL
  }

  # "Callback" to send each result-set **individually** to the client
  method callback2 {valL colL} {
    $rpc SendSTART
    $rpc SendBFL $valL
    $rpc SendBFL $colL
    $rpc SendRETURN_SUB
  }
}

# RPC callback called from service
oo::define LibSq3LiteRpcServer method Sq3LiteExecV2 {} {
  # create one THREAD-LOCAL callback instance as storage for additional attributes
  if {![info object isa object Sq3LiteExecV2Data]} {
    LibSq3LiteRpcServerExecV2IF create Sq3LiteExecV2Data
  }

  # collect service data
  set sq3lite [my Sq3LiteC_RpcRead]
  set sql     [my ReadSTR]
  set cfc     [my ReadI32]

  # initialize the "Sq3LiteExecV2Data", set the "Callback" and start the "sql" query with "ExecV2"
  $sq3lite ExecV2 $sql [Sq3LiteExecV2Data set [self] $cfc]

  # if "callback2" was used, return the MkBufferStreamC data object
  if {[my ServiceIsTransaction]} {
    if {$cfc == 1} {
      my SendSTART
      my SendBUS_FLAT [Sq3LiteExecV2Data getBUS]
    }
    my 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);

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 …