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

  public interface Sq3LiteExecIF {
    void Sq3LiteExec( string[] vals, string[] cols );
  }
    public delegate void Sq3LiteExecCCB   ( string[] vals, string[] cols );

Sq3LiteExec : callback example

    // RPC example for a callback SINGELTON to provide a callback with ARRAY-of-STRING as argument
    class Sq3LiteExecC : Sq3LiteExecIF {

      MqContextC      rpc = null;
      int             cfc = 0;

      MkBufferListC   valL;
      MkBufferListC   colL;

      public MkBufferStreamC bus;

      // constructer define local attributes
      public Sq3LiteExecC() {
        valL = new MkBufferListC();
        colL = new MkBufferListC();
        bus = new MkBufferStreamC();
      }

      void Sq3LiteExecIF.Sq3LiteExec(String[] vals, String[] cols) {

        valL.Reset().AppendLA(vals);
        colL.Reset().AppendLA(cols);

        // "cfc" determines which type of callback is used
        if (cfc == 1) {
          // "Callback" to collect **all** result sets into **one** MkBufferStreamC data object 
          // which is then sent to the client at the end with **one** response.
          bus.Reset();
          bus.WriteBFL(valL);
          bus.WriteBFL(colL);
        } else {
          // "Callback" to send each result set **individually** to the client
          rpc.SendSTART();
          rpc.SendBFL(valL);
          rpc.SendBFL(colL);
          rpc.SendRETURN_SUB();
        }
      }

      // "set" method initialize the SINGELTON callback data
      public Sq3LiteExecIF set(MqContextC myRpc, int myCfc) {
        // "cfc" determines which type of callback is used
        switch (myCfc) {
          case 0 :
            return null;
          case 1 :
          case 2 :
              rpc = myRpc;
              cfc = myCfc;
              bus.Reset();
            return this;
          default :
              MkErrorC.DEFAULT().SetC("invalid control number '" + cfc + "', expect: 0,1,2");
            return null;
        }
      }
    }

    // RPC callback called from service
    private void RpcSq3LiteExec() {
      // create one THREAD-LOCAL callback instance as storage for additional attributes
      ThreadLocal<Sq3LiteExecC> Sq3LiteExecData = 
        new ThreadLocal<Sq3LiteExecC>(() => new Sq3LiteExecC() );

      Sq3LiteC  sq3lite =  Sq3LiteC_ReadRpcHDL();
      String    sql     =  ReadStringR();
      int       cfc     =  ReadI32();

      // initialize the "Sq3LiteExecData", set the "Callback" and start the "sql" query with "ExecV2"
      sq3lite.Exec(sql, Sq3LiteExecData.Value.set(this,cfc));

      if (ServiceIsTransaction()) {
        // if "callback2" was used, return the MkBufferStreamC data object
        if (cfc == 1) {
          SendSTART();
          SendBUS_FLAT(Sq3LiteExecData.Value.bus);
        }
        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;
  }

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

  public interface Sq3LiteExecV2IF {
    void Sq3LiteExecV2( MkBufferListC vals, MkBufferListC cols );
  }
    public delegate void Sq3LiteExecV2CCB ( MkBufferListC vals, MkBufferListC cols );

Sq3LiteExecV2 : callback example with tcl OO interface

    // RPC example for a callback SINGELTON to provide a callback with MkBufferListC as argument
    class Sq3LiteExecV2C : Sq3LiteExecV2IF {

      // constructer define local attributes
      MqContextC   rpc   = null;
      int          cfc   = 0;

      public MkBufferStreamC bus;

      // constructer define local attributes
      public Sq3LiteExecV2C() {
        bus = new MkBufferStreamC();
      }

      void Sq3LiteExecV2IF.Sq3LiteExecV2 (MkBufferListC valL, MkBufferListC colL) {
        if (cfc == 1) {
          // "Callback1" to collect **all** result sets into **one** MkBufferStreamC data object 
          // which is then sent to the client at the end with **one** response.
          bus.Reset();
          bus.WriteBFL(valL);
          bus.WriteBFL(colL);
        } else {
          // "Callback2" to send each result-set **individually** to the client
          rpc.SendSTART();
          rpc.SendBFL(valL);
          rpc.SendBFL(colL);
          rpc.SendRETURN_SUB();
        }
      }

      // "set" method initialize the SINGELTON callback data
      public Sq3LiteExecV2IF set(MqContextC myRpc, int myCfc) {
        switch (myCfc) {
          case 0 :
            return null;
          case 1 :
          case 2 :
              rpc = myRpc;
              cfc = myCfc;
              bus.Reset();
            return this;
          default :
              MkErrorC.DEFAULT().SetC("invalid control number 'cfc', expect: 0,1,2");
            return null;
        }
      }
    };

    // RPC callback called from service
    private void RpcSq3LiteExecV2() {
      // create one THREAD-LOCAL callback instance as storage for additional attributes
      ThreadLocal<Sq3LiteExecV2C> Sq3LiteExecV2Data = 
        new ThreadLocal<Sq3LiteExecV2C>(() => new Sq3LiteExecV2C() );

      // collect service data
      var sq3lite =  Sq3LiteC_ReadRpcHDL();
      var sql     =  ReadStringR();
      var cfc     =  ReadI32();

      // initialize the "Sq3LiteExecV2Data", set the "Callback" and start the "sql" query with "ExecV2"
      sq3lite.ExecV2(sql, Sq3LiteExecV2Data.Value.set(this,cfc));

      // if "callback2" was used, return the MkBufferStreamC data object
      if (ServiceIsTransaction()) {
        if (cfc == 1) {
          SendSTART();
          SendBUS_FLAT(Sq3LiteExecV2Data.Value.bus);
        }
        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;
  }

Sq3LiteSleepP()

enum MkErrorE Sq3LiteSleepP

(

MK_I32

arg0

)

Non-inline replacement for Sq3LiteSleep …