libfossil
fsl_stmt Struct Reference

Represents a prepared statement handle. More...

#include "db.h"

Collaboration diagram for fsl_stmt:

Data Fields

fsl_db * db
 The db which prepared this statement.
struct { 
   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...
   uint32_t   cachedHits 
 Internal use only: counts the number of times this query has been resolved as cached via fsl_db_prepare_cached(). More...
   fsl_flag16_t   flags 
 Internal state flags. More...
   fsl_stmt *   next 
 For internal use in creating linked lists. More...
} impl
 Private implementation details.
fsl_flag16_t role
 Describes the database(s) used by this statement handle, in the form of a bitmask of fsl_dbrole_e values.
fsl_size_t rowCount
 The number of times this statement has fetched a row via fsl_stmt_step().
fsl_buffer sql
 The SQL used to prepare this statement.
fsl_stmt_t * stmt
 Underlying db driver-level statement handle.

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:
}
FSL_EXPORT const fsl_stmt fsl_stmt_empty
Empty-initialized fsl_stmt instance, intended for copy-constructing.
Definition db.h:649
FSL_EXPORT int fsl_db_prepare(fsl_db *db, fsl_stmt *tgt, char const *sql,...)
Prepares an SQL statement for execution.
FSL_EXPORT int fsl_stmt_finalize(fsl_stmt *stmt)
Frees memory associated with stmt but does not free stmt unless it was allocated by fsl_stmt_malloc()...
Represents a prepared statement handle.
Definition db.h:555
fsl_db * db
The db which prepared this statement.
Definition db.h:559
fsl_stmt_t * stmt
Underlying db driver-level statement handle.
Definition db.h:566

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...}
});
fsl_buffer sql
The SQL used to prepare this statement.
Definition db.h:585

Definition at line 555 of file db.h.

Field Documentation

◆ allocStamp

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 623 of file db.h.

◆ cachedHits

uint32_t fsl_stmt::cachedHits

Internal use only: counts the number of times this query has been resolved as cached via fsl_db_prepare_cached().

Definition at line 609 of file db.h.

◆ db

fsl_db* fsl_stmt::db

The db which prepared this statement.

Definition at line 559 of file db.h.

◆ flags

fsl_flag16_t fsl_stmt::flags

Internal state flags.

Definition at line 603 of file db.h.

◆ [struct]

struct { ... } fsl_stmt::impl

Private implementation details.

◆ next

fsl_stmt* fsl_stmt::next

For internal use in creating linked lists.

Clients must_not modify this field.

Definition at line 615 of file db.h.

◆ role

fsl_flag16_t fsl_stmt::role

Describes the database(s) used by this statement handle, in the form of a bitmask of fsl_dbrole_e values.

This is a bit of a kludge used to allow the internals to flush cached statements from the fossil global config db when detaching that database. Code which requires this to be set must set it itself and must set it correctly. Hypothetically, no client-level code requires it but some libfossil-internal code does.

Definition at line 577 of file db.h.

◆ rowCount

fsl_size_t fsl_stmt::rowCount

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

This is primarily intended for use by fsl_stmt_each_f() implementations so that they can keep track of when to emit a header (or similar pre-first-row setup).

Definition at line 593 of file db.h.

◆ sql

fsl_buffer fsl_stmt::sql

The SQL used to prepare this statement.

We keep this, rather than simply fetching the SQL on demand, only for facilitate fsl_db_prepare_cached(). But since we have it, and it might be interesting, in client code, it's a public part of the interface.

Definition at line 585 of file db.h.

◆ stmt

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 566 of file db.h.


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