Fossil

** the current command's (name,length), i.e. (argv[0],argl[0]).
*/
int Th_WrongNumArgs2(Th_Interp *interp, const char *zCmdName,
                     int zCmdLen, const char *zMsg);

typedef struct Th_SubCommand {char *zName; Th_CommandProc xProc;} Th_SubCommand;
int Th_CallSubCommand(Th_Interp*,void*,int,const char**,int*,Th_SubCommand*);






/*
** Sends the given data through vTab->out.f() if vTab->out.enabled is
** true, otherwise this is a no-op. Returns 0 or higher on success, *
** a negative value if vTab->out.f is NULL.
*/
int Th_Vtab_output( Th_Vtab *vTab, char const * zData, int len );

** the current command's (name,length), i.e. (argv[0],argl[0]).
*/
int Th_WrongNumArgs2(Th_Interp *interp, const char *zCmdName,
                     int zCmdLen, const char *zMsg);

typedef struct Th_SubCommand {char *zName; Th_CommandProc xProc;} Th_SubCommand;
int Th_CallSubCommand(Th_Interp*,void*,int,const char**,int*,Th_SubCommand*);

/*
** Works similarly to Th_CallSubCommand() but adjusts argc/argv/argl
** by 1 before passing on the call to the subcommand.
*/
int Th_CallSubCommand2(Th_Interp *interp, void *ctx, int argc, const char **argv, int *argl, Th_SubCommand *aSub);
/*
** Sends the given data through vTab->out.f() if vTab->out.enabled is
** true, otherwise this is a no-op. Returns 0 or higher on success, *
** a negative value if vTab->out.f is NULL.
*/
int Th_Vtab_output( Th_Vtab *vTab, char const * zData, int len );

      return aSub[i].xProc(interp, ctx, argc, argv, argl);
    }
  }

  Th_ErrorMessage(interp, "Expected sub-command, got:", argv[1], argl[1]);
  return TH_ERROR;
}





















/*
** TH Syntax:
**
**   string compare STR1 STR2
**   string first   NEEDLE HAYSTACK ?STARTINDEX?
**   string is      CLASS STRING

      return aSub[i].xProc(interp, ctx, argc, argv, argl);
    }
  }

  Th_ErrorMessage(interp, "Expected sub-command, got:", argv[1], argl[1]);
  return TH_ERROR;
}

int Th_CallSubCommand2(
  Th_Interp *interp, 
  void *ctx,
  int argc,
  const char **argv,
  int *argl,
  Th_SubCommand *aSub
){
  int i;
  for(i=0; aSub[i].zName; i++){
    char const *zName = aSub[i].zName;
    if( th_strlen(zName)==argl[1] && 0==memcmp(zName, argv[1], argl[1]) ){
      return aSub[i].xProc(interp, ctx, argc-1, argv+1, argl+1);
    }
  }
  Th_ErrorMessage(interp, "Expected sub-command, got:", argv[1], argl[1]);
  return TH_ERROR;
}


/*
** TH Syntax:
**
**   string compare STR1 STR2
**   string first   NEEDLE HAYSTACK ?STARTINDEX?
**   string is      CLASS STRING

  rc = sqlite3_bind_double( pStmt, index, val );
  if(rc){
    return queryReportDbErr( interp );
  }
  Th_SetResultInt( interp, 0 );
  return TH_OK;
}




























int th_register_sqlite(Th_Interp *interp){
  enum { BufLen = 100 };
  char buf[BufLen];
  int i, l;
#define SET(K) l = snprintf(buf, BufLen, "%d", K);      \
  Th_SetVar( interp, #K, strlen(#K), buf, l );
................................................................................
  SET(SQLITE_INTEGER);
  SET(SQLITE_NULL);
  SET(SQLITE_OK);
  SET(SQLITE_ROW);
  SET(SQLITE_TEXT);
#undef SET
  static Th_Command_Reg aCommand[] = {


    {"query_bind_int",    queryBindIntCmd,   0},
    {"query_bind_double", queryBindDoubleCmd,0},
    {"query_bind_null",   queryBindNullCmd,  0},
    {"query_bind_string", queryBindStringCmd,0},
    {"query_col_count",   queryColCountCmd,  0},
    {"query_col_double",  queryColDoubleCmd, 0},
    {"query_col_int",     queryColIntCmd,    0},
................................................................................
    {"query_col_is_null", queryColIsNullCmd, 0},
    {"query_col_name",    queryColNameCmd,   0},
    {"query_col_string",  queryColStringCmd, 0},
    {"query_col_type",    queryColTypeCmd,   0},
    {"query_finalize",    queryFinalizeCmd,  0},
    {"query_prepare",     queryPrepareCmd,   0},
    {"query_step",        queryStepCmd,      0},

    {0, 0, 0}
  };
  Th_register_commands( interp, aCommand );
}

#endif
/* end TH_USE_SQLITE */

  rc = sqlite3_bind_double( pStmt, index, val );
  if(rc){
    return queryReportDbErr( interp );
  }
  Th_SetResultInt( interp, 0 );
  return TH_OK;
}

static int queryTopLevelCmd(
  Th_Interp *interp,
  void *ctx, 
  int argc, 
  const char **argv, 
  int *argl
){
  static Th_SubCommand aSub[] = {
    {"bind_int",    queryBindIntCmd},
    {"bind_double", queryBindDoubleCmd},
    {"bind_null",   queryBindNullCmd},
    {"bind_string", queryBindStringCmd},
    {"col_count",   queryColCountCmd},
    {"col_double",  queryColDoubleCmd},
    {"col_int",     queryColIntCmd},
    {"col_is_null", queryColIsNullCmd},
    {"col_name",    queryColNameCmd},
    {"col_string",  queryColStringCmd},
    {"col_type",    queryColTypeCmd},
    {"step",        queryStepCmd},
    {"finalize",    queryFinalizeCmd},
    {"prepare",     queryPrepareCmd},
    {0, 0}
  };
  Th_CallSubCommand2( interp, ctx, argc, argv, argl, aSub );
}

int th_register_sqlite(Th_Interp *interp){
  enum { BufLen = 100 };
  char buf[BufLen];
  int i, l;
#define SET(K) l = snprintf(buf, BufLen, "%d", K);      \
  Th_SetVar( interp, #K, strlen(#K), buf, l );
................................................................................
  SET(SQLITE_INTEGER);
  SET(SQLITE_NULL);
  SET(SQLITE_OK);
  SET(SQLITE_ROW);
  SET(SQLITE_TEXT);
#undef SET
  static Th_Command_Reg aCommand[] = {
    {"query",             queryTopLevelCmd,  0},
#if 0
    {"query_bind_int",    queryBindIntCmd,   0},
    {"query_bind_double", queryBindDoubleCmd,0},
    {"query_bind_null",   queryBindNullCmd,  0},
    {"query_bind_string", queryBindStringCmd,0},
    {"query_col_count",   queryColCountCmd,  0},
    {"query_col_double",  queryColDoubleCmd, 0},
    {"query_col_int",     queryColIntCmd,    0},
................................................................................
    {"query_col_is_null", queryColIsNullCmd, 0},
    {"query_col_name",    queryColNameCmd,   0},
    {"query_col_string",  queryColStringCmd, 0},
    {"query_col_type",    queryColTypeCmd,   0},
    {"query_finalize",    queryFinalizeCmd,  0},
    {"query_prepare",     queryPrepareCmd,   0},
    {"query_step",        queryStepCmd,      0},
#endif
    {0, 0, 0}
  };
  Th_register_commands( interp, aCommand );
}

#endif
/* end TH_USE_SQLITE */

proc xyz {} {
        return 42
}
set a [xyz]
puts "a=${a}" ! \n

set stmt [query_prepare {SELECT login, cap FROM user}]
set colCount [query_col_count $stmt]
puts "query column count: ${colCount}\n"
puts "stmt id=${stmt}\n"

proc noop {} {}
proc incr {name {step 1}} {
    upvar $name x
    set x [expr $x+$step]
................................................................................
}


set sep "    "
set i 0
set colNames(0) 0
for {set i 0} {$i < $colCount} {incr i} {
    set colNames($i) [query_col_name $stmt $i]
    puts "colNames($i)=" $colNames($i) "\n"
}

for {set row 0} {0 < [query_step $stmt]} {incr row} {
    for {set i 0} {$i < $colCount} {incr i} {
        if {$i > 0} {
            puts $sep
        } else {
            puts "#$row: $sep"
        }
        puts $colNames($i) = [query_col_string $stmt $i]
    }
    puts "\n"
}
unset row

query_finalize $stmt


proc query_step_each {{stmt} {callback}} {
    set colNames(0) 0
    set colCount [query_col_count $stmt]
    for {set i 0} {$i < $colCount} {incr i} {
        set colNames($i) [query_col_name $stmt $i]
    }
    upvar cb $callback
    for {set row 0} {0 < [query_step $stmt]} {incr row} {
        #puts "Calling callback: $stmt $colCount colNames\n"
        $callback $stmt $colCount
    }
}

set sql {SELECT uid, login FROM user WHERE uid!=?}
#set sql {SELECT uid, login FROM user WHERE login=?}
#set sql {SELECT tagid, value, null FROM tagxref WHERE value IS ? LIMIT 3}
set stmt [query_prepare $sql]
puts "stmt ID=" $stmt "\n"
query_bind_int $stmt 1 3
#set stmt [query_prepare $sql]
#query_bind_string $stmt 1 stephan
#set stmt [query_prepare $sql]
#query_bind_null $stmt 1
set rc 0
puts "USER LIST:\n"
catch {
    proc my_each {stmt colCount} {
        upvar 2 sep sep
        puts [query_col_int $stmt 0] " (type=" [query_col_type $stmt 0] ")" $sep
        puts [query_col_double $stmt 0] $sep
        puts [query_col_string $stmt 1]  " (type=" [query_col_type $stmt 1] ")" $sep
        puts "isnull 0 ?= " [query_col_is_null $stmt 0] $sep
        puts "isnull 2 ?= " [query_col_is_null $stmt 2]
#        for {set i 0} {$i < $colCount} {incr i} {
#            if {$i > 0} { puts $sep }
#        }
        puts "\n"
#        error "hi!"
    }
    query_step_each $stmt my_each
#    query_step_each $stmt {
#        proc each {stmt cc} { puts hi "\n" }
#    }
} rc
query_finalize $stmt
puts rc = $rc "\n"

set consts [list SQLITE_BLOB SQLITE_DONE SQLITE_ERROR SQLITE_FLOAT SQLITE_INTEGER SQLITE_NULL SQLITE_OK SQLITE_ROW SQLITE_TEXT]
#set consts $SQLITE_CONSTANTS
puts consts = $consts "\n"
for {set i 0} {$i < [llength $consts]} {incr i} {
    set x [lindex $consts $i]
................................................................................
enable_output 1

proc multiStmt {} {
    set max 5
    set i 0
    set s(0) 0
    for {set i 0} {$i < $max} {incr i} {
       set s($i) [query_prepare "SELECT $i"]
       puts "s($i) = $s($i)\n"
    }
    for {set i 0} {$i < $max} {incr i} {
       query_step $s($i)
    }
    for {set i 0} {$i < $max} {incr i} {
       puts "closing stmt $s($i)\n"
       query_finalize $s($i)
    }

    puts "Preparing again\n"

    for {set i 0} {$i < $max} {incr i} {
       set s($i) [query_prepare "SELECT $i"]
       puts "s($i) = $s($i)\n"
    }
    for {set i 0} {$i < $max} {incr i} {
       query_step $s($i)
    }
    puts "Closing again\n"

    for {set i 0} {$i < $max} {incr i} {
       puts "closing stmt $s($i)\n"
       query_finalize $s($i)
    }
}
multiStmt

enable_output 1
puts "If you got this far, you win!\n"
</th1>

proc xyz {} {
        return 42
}
set a [xyz]
puts "a=${a}" ! \n

set stmt [query prepare {SELECT login, cap FROM user}]
set colCount [query col_count $stmt]
puts "query column count: ${colCount}\n"
puts "stmt id=${stmt}\n"

proc noop {} {}
proc incr {name {step 1}} {
    upvar $name x
    set x [expr $x+$step]
................................................................................
}


set sep "    "
set i 0
set colNames(0) 0
for {set i 0} {$i < $colCount} {incr i} {
    set colNames($i) [query col_name $stmt $i]
    puts "colNames($i)=" $colNames($i) "\n"
}

for {set row 0} {0 < [query step $stmt]} {incr row} {
    for {set i 0} {$i < $colCount} {incr i} {
        if {$i > 0} {
            puts $sep
        } else {
            puts "#$row: $sep"
        }
        puts $colNames($i) = [query col_string $stmt $i]
    }
    puts "\n"
}
unset row

query finalize $stmt


proc query_step_each {{stmt} {callback}} {
    set colNames(0) 0
    set colCount [query col_count $stmt]
    for {set i 0} {$i < $colCount} {incr i} {
        set colNames($i) [query col_name $stmt $i]
    }
    upvar cb $callback
    for {set row 0} {0 < [query step $stmt]} {incr row} {
        #puts "Calling callback: $stmt $colCount colNames\n"
        $callback $stmt $colCount
    }
}

set sql {SELECT uid, login FROM user WHERE uid!=?}
#set sql {SELECT uid, login FROM user WHERE login=?}
#set sql {SELECT tagid, value, null FROM tagxref WHERE value IS ? LIMIT 3}
set stmt [query prepare $sql]
puts "stmt ID=" $stmt "\n"
query bind_int $stmt 1 3
#set stmt [query prepare $sql]
#query bind_string $stmt 1 stephan
#set stmt [query prepare $sql]
#query bind_null $stmt 1
set rc 0
puts "USER LIST:\n"
catch {
    proc my_each {stmt colCount} {
        upvar 2 sep sep
        puts [query col_int $stmt 0] " (type=" [query col_type $stmt 0] ")" $sep
        puts [query col_double $stmt 0] $sep
        puts [query col_string $stmt 1]  " (type=" [query col_type $stmt 1] ")" $sep
        puts "isnull 0 ?= " [query col_is_null $stmt 0] $sep
        puts "isnull 2 ?= " [query col_is_null $stmt 2]
#        for {set i 0} {$i < $colCount} {incr i} {
#            if {$i > 0} { puts $sep }
#        }
        puts "\n"
#        error "hi!"
    }
    query step_each $stmt my_each
#    query step_each $stmt {
#        proc each {stmt cc} { puts hi "\n" }
#    }
} rc
query finalize $stmt
puts rc = $rc "\n"

set consts [list SQLITE_BLOB SQLITE_DONE SQLITE_ERROR SQLITE_FLOAT SQLITE_INTEGER SQLITE_NULL SQLITE_OK SQLITE_ROW SQLITE_TEXT]
#set consts $SQLITE_CONSTANTS
puts consts = $consts "\n"
for {set i 0} {$i < [llength $consts]} {incr i} {
    set x [lindex $consts $i]
................................................................................
enable_output 1

proc multiStmt {} {
    set max 5
    set i 0
    set s(0) 0
    for {set i 0} {$i < $max} {incr i} {
       set s($i) [query prepare "SELECT $i"]
       puts "s($i) = $s($i)\n"
    }
    for {set i 0} {$i < $max} {incr i} {
       query step $s($i)
    }
    for {set i 0} {$i < $max} {incr i} {
       puts "closing stmt $s($i)\n"
       query finalize $s($i)
    }

    puts "Preparing again\n"

    for {set i 0} {$i < $max} {incr i} {
       set s($i) [query prepare "SELECT $i"]
       puts "s($i) = $s($i)\n"
    }
    for {set i 0} {$i < $max} {incr i} {
       query step $s($i)
    }
    puts "Closing again\n"

    for {set i 0} {$i < $max} {incr i} {
       puts "closing stmt $s($i)\n"
       query finalize $s($i)
    }
}
multiStmt

enable_output 1
puts "If you got this far, you win!\n"
</th1>

<h1>TH1 "query" API</h1>

The "query" API provides limited access to the fossil database.
It restricts usage to queries which return result columns (i.e.
<tt>SELECT</tt> and friends).
Example usage:

<nowiki><pre>
&lt;th1>
catch {
    set stmt [query prepare "SELECT login, cap FROM user"]
    puts "stmt ID=$stmt\n"
    for {} {0 < [query step $stmt]} {} {
        puts [query col_string $stmt 0] ": " [query col_string $stmt 1] "\n"
    }
    query finalize $stmt
    return 0
} rc
if {0 != $rc} {
    puts "ERROR: $rc\n"
}
&lt;th1>
</pre></nowiki>

The various subcommands are summarized below...

<h2>prepare</h2>

This subcommand prepares a query for execution. It returns a statement handle
ID which must be passed to any other functions using the API.

All prepared statements must be <tt>finalize</tt>d when they have outlived
their usefulness.

<h2>finalize</h2>

Releases all resources associated with the statement. Note that future
calls to <tt>prepare</tt> might re-use the same statement statement
ID.

<nowiki><pre>
set stmt [query prepare "SELECT ..."]
query finalize $stmt
</pre></nowiki>


<h2>step</h2>

This subcommand steps the result set by one row. It returns 0
at the end of the set, a positive value if a new row is available,
and throws for any other condition.

<nowiki><pre>
for {} {0 &lt; [query step $stmt]} {} {
   puts [query col_string $stmt 0] "\n"
}
</pre></nowiki>


<h2>bind_xxx</h2>

The <tt>bind_xxx</tt> family of subcommands attach values to queries
before stepping through them. The subcommands include:

   *  <tt>bind_int StmtId Index Value</tt>
   *  <tt>bind_double StmtId Index Value</tt>
   *  <tt>bind_null StmtId Index</tt>
   *  <tt>bind_string StmtId Index Value</tt>

Achtung: the bind API uses 1-based indexes, just like SQL does.

TODO: split bind_xxx into "bind xxx".

<nowiki><pre>
set stmt [query prepare "SELECT ... WHERE user=?"]
query bind_int $stmt 1 drh
if {0 &lt; [query step $stmt]} {
   puts [query col_string $stmt 0] "\n"
}
query finalize $stmt
</pre></nowiki>


<h2>col_xxx</h2>

The <tt>col_xxx</tt> familys of subcommands are for fetching
values and metadata from result rows.

   *  <tt>col_count StmtId</tt> Returns the number of result columns in the statement.
   *  <tt>col_is_null StmtId Index</tt> Returns non-0 if the given column contains an SQL NULL value.
   *  <tt>col_double StmtId Index</tt>
   *  <tt>col_int StmtId Index</tt>
   *  <tt>col_string StmtId Index</tt>
   *  <tt>col_type StmtId Index</tt> Return value corresponds to one of the <tt>SQLITE_TYPENAME</tt> family of constants.

TODO: split col_xxx into "col xxx".

Achtung: the col API uses 0-based indexes, just like SQL does.