libfossil
fsl_stmt Struct Reference

Represents a prepared statement handle. More...

#include "fossil-db.h"

Data Fields

void const * allocStamp
 A marker which tells fsl_stmt_finalize() whether or not fsl_stmt_malloc() allocated this instance (in which case fsl_stmt_finalize() will fsl_free() it) or not (in which case it does not free() it). More...
 
int colCount
 Number of result columns in this statement. More...
 
fsl_dbdb
 The db which prepared this statement. More...
 
int flags
 Internal state flags. More...
 
fsl_stmtnext
 For _internal_ use in creating linked lists. More...
 
int paramCount
 Number of bound parameter indexes in this statement. More...
 
fsl_size_t rowCount
 The number of times this statement has fetched a row via fsl_stmt_step(). More...
 
fsl_buffer sql
 SQL used to prepare this statement. More...
 
fsl_stmt_tstmt
 Underlying db driver-level statement handle. More...
 

Detailed Description

Represents a prepared statement handle.

Intended usage:

int rc = fsl_db_prepare( db, &st, "..." );
if(rc){ // Error!
assert(!st.stmt);
// db->error might hold driver-level error details.
}else{
// use st and eventually finalize it:
}

Script binding implementations can largely avoid exposing the statement handle (and its related cleanup ordering requirements) to script code. They need to have some mechanism for binding values to SQL (or implement all the escaping themselves), but that can be done without exposing all of the statement class if desired. For example, here's some hypothetical script code:

var st = db.prepare(".... where i=:i and x=:x");
// st is-a Statement, but we need not add script bindings for
// the whole Statement.bind() API. We can instead simplify that
// to something like:
try {
st.exec( {i: 42, x: 3} )
// or, for a SELECT query:
st.each({
bind{i:42, x:3},
rowType: 'array', // or 'object'
callback: function(row,state,colNames){ print(row.join('\t')); },
state: {...callback function state...}
});
} finally {
st.finalize();
// It is critical that st gets finalized before its DB, and
// that'shard to guaranty if we leave st to the garbage collector!
}
// see below for another (less messy) alternative

Ideally, script code should not have direct access to the Statement because managing lifetimes can be difficult in the face of flow-control changes caused by exceptions (as the above example demonstrates). Statements can be completely hidden from clients if the DB wrapper is written to support it. For example, in pseudo-JavaScript that might look like:

db.exec("...where i=? AND x=?", 42, 3);
db.each({sql:"select ... where id<?", bind:[10],
rowType: 'array', // or 'object'
callback: function(row,state,colNames){ print(row.join('\t')); },
state: {...arbitrary state for the callback...}
});

Definition at line 321 of file fossil-db.h.

Field Documentation

void const* fsl_stmt::allocStamp

A marker which tells fsl_stmt_finalize() whether or not fsl_stmt_malloc() allocated this instance (in which case fsl_stmt_finalize() will fsl_free() it) or not (in which case it does not free() it).

Definition at line 376 of file fossil-db.h.

int fsl_stmt::colCount

Number of result columns in this statement.

Cached when the statement is prepared. Is a signed type because the underlying API does it this way.

Definition at line 344 of file fossil-db.h.

fsl_db* fsl_stmt::db

The db which prepared this statement.

Definition at line 325 of file fossil-db.h.

int fsl_stmt::flags

Internal state flags.

Definition at line 362 of file fossil-db.h.

fsl_stmt* fsl_stmt::next

For _internal_ use in creating linked lists.

Clients _must_not_ modify this field.

Definition at line 368 of file fossil-db.h.

int fsl_stmt::paramCount

Number of bound parameter indexes in this statement.

Cached when the statement is prepared. Is a signed type because the underlying API does it this way.

Definition at line 351 of file fossil-db.h.

fsl_size_t fsl_stmt::rowCount

The number of times this statement has fetched a row via fsl_stmt_step().

Definition at line 357 of file fossil-db.h.

fsl_buffer fsl_stmt::sql

SQL used to prepare this statement.

Definition at line 337 of file fossil-db.h.

fsl_stmt_t* fsl_stmt::stmt

Underlying db driver-level statement handle.

Clients should not rely on the specify concrete type if they can avoid it, to simplify an eventual port from sqlite3 to sqlite4.

Definition at line 332 of file fossil-db.h.


The documentation for this struct was generated from the following file: