libfossil
fossil-db.h
Go to the documentation of this file.
1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=2 et sw=2 tw=80: */
3 #if !defined(NET_FOSSIL_SCM_FSL_DB_H_INCLUDED)
4 #define NET_FOSSIL_SCM_FSL_DB_H_INCLUDED
5 /*
6  Copyright (c) 2013 D. Richard Hipp
7 
8  This program is free software; you can redistribute it and/or
9  modify it under the terms of the Simplified BSD License (also
10  known as the "2-Clause License" or "FreeBSD License".)
11 
12  This program is distributed in the hope that it will be useful,
13  but without any warranty; without even the implied warranty of
14  merchantability or fitness for a particular purpose.
15 
16  Author contact information:
17  drh@hwaci.com
18  http://www.hwaci.com/drh/
19 
20  ******************************************************************************
21  This file declares public APIs for working with fossil's database
22  abstraction layer.
23 */
24 
25 #include "fossil-core.h" /* MUST come first b/c of config macros */
26 /*
27  We don't _really_ want to include sqlite3.h at this point, but if we
28  do not then we have to typedef the sqlite3 struct here and that
29  breaks when client code includes both this file and sqlite3.h.
30 */
31 #include "sqlite3.h"
32 
33 #if defined(__cplusplus)
34 extern "C" {
35 #endif
36 
37 /**
38  Potential TODO. Maybe not needed - v1 uses only(?) 1 hook and we
39  can do that w/o hooks.
40 */
41 typedef int (*fsl_commit_hook_f)( void * state );
42 /** Potential TODO */
45  int sequence;
46  void * state;
47 };
48 #define fsl_commit_hook_empty_m {NULL,0,NULL}
50 /* extern const fsl_commit_hook fsl_commit_hook_empty; */
51 
52 /**
53  Potential TODO.
54 */
56  int sequence, void * state );
57 
58 
59 #if 0
60 /* We can't do this because it breaks when clients include both
61  this header and sqlite3.h. Is there a solution which lets us
62  _not_ include sqlite3.h from this file and also compiles when
63  clients include both?
64 */
65 #if !defined(SQLITE_OK)
66 /**
67  Placeholder for sqlite3/4 type. We currently use v3 but will
68  almost certainly switch to v4 at some point. Before we can do
69  that we need an upgrade/migration path.
70 */
71 typedef struct sqlite3 sqlite3;
72 #endif
73 #endif
74 
75 /**
76  A level of indirection to "hide" the actual db driver
77  implementation from the public API. Whether or not the API
78  uses/will use sqlite3 or 4 is "officially unspecified." We
79  currently use 3 because (A) it bootstraps development and
80  testing by letting us use existing fossil repos for and (B) it
81  reduces the number of potential problems when porting SQL-heavy
82  code from the v1 tree. Clients should try not to rely on the
83  underlying db driver API, but may need it for some uses
84  (e.g. binding custom SQL functions).
85 */
86 typedef sqlite3 fsl_dbh_t;
87 
88 /**
89  Db handle wrapper class. Each instance wraps a single sqlite
90  database handle.
91 
92  Fossil is built upon sqlite3, but this abstraction is intended
93  to hide that, insofar as possible, from clients so as to
94  simplify an eventual port from v3 to v4. Clients should avoid
95  relying on the underlying db being sqlite (or at least not rely
96  on a specific version), but may want to register custom
97  functions with the driver (or perform similar low-level
98  operations) and the option is left open for them to access that
99  handle via the fsl_db::dbh member.
100 
101  @see fsl_db_open();
102  @see fsl_db_close();
103  @see fsl_stmt
104 */
105 struct fsl_db {
106  /**
107  Fossil Context on whose behalf this instance is operating, if
108  any. Certain db operations behave differently depending
109  on whether or not this is NULL.
110  */
112 
113  /**
114  Describes what role(s) this db connection plays in fossil (if
115  any). This is a bitmask of fsl_db_role_t values, and a db
116  connection may have multiple roles. This is only used by the
117  fsl_cx-internal API.
118  */
119  int role;
120 
121  /**
122  Underlying db driver handle.
123  */
124  fsl_dbh_t * dbh;
125 
126  /**
127  Holds error state from the underlying driver. fsl_db and
128  fsl_stmt operations which fail at the driver level "should"
129  update this state to include error info from the driver.
130  fsl_cx APIs which fail at the DB level uplift this (using
131  fsl_error_move()) so that they can pass it on up the call chain.
132  */
134 
135  /**
136  Holds the file name used when opening this db. Might not refer to
137  a real file (e.g. might be ":memory:" or "" (similar to
138  ":memory:" but may swap to temp storage).
139  */
140  char * filename;
141 
142  /**
143  Holds the database name for use in creating queries.
144  Might or might not be set/needed, depending on
145  the context.
146  */
147  char * name;
148 
149  /**
150  Debugging/test counter. Closing a db with opened statements
151  might assert() or trigger debug output when the db is closed.
152  */
154 
155  /**
156  Counter for fsl_db_transaction_begin/end().
157  */
159 
160  /**
161  Internal flag for communicating rollback state through the
162  call stack. If this is set to a true value,
163  fsl_db_transaction_end() calls will behave like a rollback
164  regardless of the value of the 2nd argument passed to that
165  function. i.e. it propagates a rollback through nested
166  transactions.
167 
168  Potential TODO: instead of treating this like a boolean, store
169  the error number which caused the rollback here. We'd have to
170  go fix a lot of code for that, though :/.
171  */
173 
174  /**
175  Internal change counter. Set when a transaction is
176  started/committed.
177 
178  Maintenance note: it's an int because that's what
179  sqlite3_total_changes() returns.
180  */
182 
183  /**
184  List of SQL commands (char *) which should be executed prior
185  to a commit. This list is cleared when the transaction counter
186  drops to zero as the result of fsl_db_transaction_end()
187  or fsl_db_rollback_force().
188 
189  TODO? Use (fsl_stmt*) objects instead of strings? Depends on
190  how much data we need to bind here (want to avoid an extra
191  copy if we need to bind big stuff). That was implemented in
192  [9d9375ac2d], but that approach prohibits multi-statement
193  pre-commit triggers, so it was not trunked. It's still unknown
194  whether we need multi-statement SQL in this context
195  (==fossil's infrastructure).
196 
197  @see fsl_db_before_commit()
198  */
200 
201  /**
202  An internal cache of "static" queries - those which do not
203  rely on call-time state unless that state can be
204  bind()ed. Holds a linked list of (fsl_stmt*) instances.
205 
206  @see fsl_db_prepare_cached()
207  */
209 
210  /**
211  A marker which tells fsl_db_close() whether or not
212  fsl_db_malloc() allocated this instance (in which case
213  fsl_db_close() will fsl_free() it) or not (in which case it
214  does not free() it).
215  */
216  void const * allocStamp;
217 };
218 /**
219  Empty-initialized fsl_db structure, intended for const-copy
220  initialization.
221 */
222 #define fsl_db_empty_m { \
223  NULL/*f*/, \
224  FSL_DB_ROLE_NONE, \
225  NULL/*dbh*/, \
226  fsl_error_empty_m /*error*/, \
227  NULL/*filename*/, \
228  NULL/*name*/, \
229  0/*openStatementCount*/, \
230  0/*beginCount*/, \
231  0/*doRollback*/, \
232  0/*priorChanges*/, \
233  fsl_list_empty_m/*beforeCommit*/, \
234  NULL/*cacheHead*/, \
235  NULL/*allocStamp*/ \
236  }
237 
238 /**
239  Empty-initialized fsl_db structure, intended for copy
240  initialization.
241 */
243 
244 /**
245  If db is not NULL then this function returns its name (the one
246  used to open it). The bytes are valid until the db connection is
247  closed or until someone mucks with db->filename. If len is not
248  NULL then *len is (on success) assigned to the length of the
249  returned string, in bytes. The string is NUL-terminated, so
250  fetching the length (by passing a non-NULL 2nd parameter) is
251  optional but sometimes helps improve efficiency be removing
252  the need for a downstream call to fsl_strlen().
253 
254  Returns NULL if !f or f has no checkout opened.
255 */
256 FSL_EXPORT char const * fsl_db_filename(fsl_db const * db, fsl_size_t * len);
257 
258 typedef sqlite3_stmt fsl_stmt_t;
259 /**
260  Represents a prepared statement handle.
261  Intended usage:
262 
263  @code
264  fsl_stmt st = fsl_stmt_empty;
265  int rc = fsl_db_prepare( db, &st, "..." );
266  if(rc){ // Error!
267  assert(!st.stmt);
268  // db->error might hold driver-level error details.
269  }else{
270  // use st and eventually finalize it:
271  fsl_stmt_finalize( &st );
272  }
273  @endcode
274 
275 
276  Script binding implementations can largely avoid exposing the
277  statement handle (and its related cleanup ordering requirements)
278  to script code. They need to have some mechanism for binding
279  values to SQL (or implement all the escaping themselves), but
280  that can be done without exposing all of the statement class if
281  desired. For example, here's some hypothetical script code:
282 
283  @code
284  var st = db.prepare(".... where i=:i and x=:x");
285  // st is-a Statement, but we need not add script bindings for
286  // the whole Statement.bind() API. We can instead simplify that
287  // to something like:
288  try {
289  st.exec( {i: 42, x: 3} )
290  // or, for a SELECT query:
291  st.each({
292  bind{i:42, x:3},
293  rowType: 'array', // or 'object'
294  callback: function(row,state,colNames){ print(row.join('\t')); },
295  state: {...callback function state...}
296  });
297  } finally {
298  st.finalize();
299  // It is critical that st gets finalized before its DB, and
300  // that'shard to guaranty if we leave st to the garbage collector!
301  }
302  // see below for another (less messy) alternative
303  @endcode
304 
305  Ideally, script code should not have direct access to the
306  Statement because managing lifetimes can be difficult in the
307  face of flow-control changes caused by exceptions (as the above
308  example demonstrates). Statements can be completely hidden from
309  clients if the DB wrapper is written to support it. For example,
310  in pseudo-JavaScript that might look like:
311 
312  @code
313  db.exec("...where i=? AND x=?", 42, 3);
314  db.each({sql:"select ... where id<?", bind:[10],
315  rowType: 'array', // or 'object'
316  callback: function(row,state,colNames){ print(row.join('\t')); },
317  state: {...arbitrary state for the callback...}
318  });
319  @endcode
320 */
321 struct fsl_stmt {
322  /**
323  The db which prepared this statement.
324  */
326 
327  /**
328  Underlying db driver-level statement handle. Clients should
329  not rely on the specify concrete type if they can avoid it, to
330  simplify an eventual port from sqlite3 to sqlite4.
331  */
332  fsl_stmt_t * stmt;
333 
334  /**
335  SQL used to prepare this statement.
336  */
338 
339  /**
340  Number of result columns in this statement. Cached when the
341  statement is prepared. Is a signed type because the underlying
342  API does it this way.
343  */
344  int colCount;
345 
346  /**
347  Number of bound parameter indexes in this statement. Cached
348  when the statement is prepared. Is a signed type because the
349  underlying API does it this way.
350  */
352 
353  /**
354  The number of times this statement has fetched a row via
355  fsl_stmt_step().
356  */
358 
359  /**
360  Internal state flags.
361  */
362  int flags;
363 
364  /**
365  For _internal_ use in creating linked lists. Clients _must_not_
366  modify this field.
367  */
369 
370  /**
371  A marker which tells fsl_stmt_finalize() whether or not
372  fsl_stmt_malloc() allocated this instance (in which case
373  fsl_stmt_finalize() will fsl_free() it) or not (in which case
374  it does not free() it).
375  */
376  void const * allocStamp;
377 };
378 /**
379  Empty-initialized fsl_stmt instance, intended for use as an
380  in-struct initializer.
381 */
382 #define fsl_stmt_empty_m { \
383  NULL/*db*/, \
384  NULL/*stmt*/, \
385  fsl_buffer_empty_m/*sql*/, \
386  0/*colCount*/, \
387  0/*paramCount*/, \
388  0/*rowCount*/, \
389  1/*flags*/, \
390  NULL/*next*/, \
391  NULL/*allocStamp*/ \
392  }
393 
394 /**
395  Empty-initialized fsl_stmt instance, intended for
396  copy-constructing.
397 */
399 
400 /**
401  Allocates a new, cleanly-initialized fsl_stmt instance using
402  fsl_malloc(). The returned pointer must eventually be passed to
403  fsl_stmt_finalize() to free it (whether or not it is ever passed
404  to fsl_db_prepare()).
405 
406  Returns NULL on allocation error.
407 */
409 
410 
411 /**
412  If db is not NULL this behaves like fsl_error_get(), using the
413  db's underlying error state. If !db then it returns
414  FSL_RC_MISUSE.
415 */
416 FSL_EXPORT int fsl_db_err_get( fsl_db const * db, char const ** msg, fsl_size_t * len );
417 
418 /**
419  Resets any error state in db, but might keep the string
420  memory allocated for later use.
421 */
422 FSL_EXPORT void fsl_db_err_reset( fsl_db * db );
423 
424 /**
425  Prepares an SQL statement for execution. On success it returns
426  0, populates tgt with the statement's state, and the caller is
427  obligated to eventually pass tgt to fsl_stmt_finalize(). tgt
428  must have been cleanly initialized, either via allocation via
429  fsl_stmt_malloc() or by copy-constructing fsl_stmt_empty
430  resp. fsl_stmt_empty_m (depending on the context).
431 
432  On error non-0 is returned and tgt is not modified. If
433  preparation of the statement fails at the db level then
434  FSL_RC_DB is returned f's error state (fsl_cx_err_get())
435  "should" contain more details about the problem. Returns
436  FSL_RC_MISUSE if !db, !callback, or !sql. Returns
437  FSL_RC_NOT_FOUND if db is not opened. Returns FSL_RC_RANGE if
438  !*sql.
439 
440  The sql string and the following arguments get routed through
441  fsl_appendf(), so any formatting options supported by that
442  routine may be used here. In particular, the %%q and %%Q
443  formatting options are intended for use in escaping SQL for
444  routines such as this one.
445 
446  Compatibility note: in sqlite, empty SQL code evaluates
447  successfully but with a NULL statement. This API disallows empty
448  SQL because it uses NULL as a "no statement" marker and because
449  empty SQL is arguably not a query at all.
450 
451  Tips:
452 
453  - fsl_stmt_col_count() can be used to determine whether a
454  statement is a fetching query (fsl_stmt_col_count()>0) or not
455  (fsl_stmt_col_count()==0) without having to know the contents
456  of the query.
457 
458  - fsl_db_prepare_cached() can be used to cache often-used or
459  expensive-to-prepare queries within the context of their parent
460  db handle.
461 */
462 FSL_EXPORT int fsl_db_prepare( fsl_db *db, fsl_stmt * tgt, char const * sql, ... );
463 
464 /**
465  va_list counterpart of fsl_db_prepare().
466 */
467 FSL_EXPORT int fsl_db_preparev( fsl_db *db, fsl_stmt * tgt, char const * sql, va_list args );
468 
469 /**
470  A special-purpose variant of fsl_db_prepare() which caches
471  statements based on their SQL code. This works very much like
472  fsl_db_prepare() and friends except that it can return the same
473  statement (via *st) multiple times (statements with identical
474  SQL are considered equivalent for caching purposes). Clients
475  need not explicitly pass the returned statement to
476  fsl_stmt_finalize() - the db holds these statements and will
477  finalize them when it is closed. It is legal to pass them to
478  finalize, in which case they will be cleaned up immediately but
479  that also invalidates _all_ pointers to the shared instances.
480 
481  If client code does not call fsl_stmt_finalize(), it MUST pass
482  the statement pointer to fsl_stmt_cached_yield(st) after is done
483  with it. That makes the query available for use again with this
484  routine. If a cached query is not yielded via
485  fsl_stmt_cached_yield() then this routine will return
486  FSL_RC_ACCESS on subsequent requests for that SQL to prevent
487  that recursive (mis)use of the statement causes problems.
488 
489  This routine is intended to be used in oft-called routines
490  where the cost of re-creating statements on each execution could
491  be prohibitive (or at least a bummer).
492 
493  Returns 0 on success, FSL_RC_MISUSE if any arguments are
494  invalid. On other error's db->error might be updated with more
495  useful information. See the Caveats section below for more
496  details.
497 
498  Its intended usage looks like:
499 
500  @code
501  fsl_stmt * st = NULL;
502  int rc = fsl_db_prepare_cached(myDb, &st, "SELECT ...");
503  if(rc) { assert(!st); ...error... }
504  else {
505  ...use it, and _be sure_ to yield it when done:...
506  fsl_stmt_cached_yield(st);
507  }
508  @endcode
509 
510  Though this function allows a formatted SQL string, caching is
511  generally only useful with statements which have "static" SQL,
512  i.e. no call-dependent values embedded within the SQL. It _can_,
513  however, contain bind() placeholders which get reset for each
514  use. Note that fsl_stmt_cached_yield() resets the statement, so
515  most uses of cached statements do not require that the client
516  explicitly reset cached statements (doing so is harmless,
517  however).
518 
519  Caveats:
520 
521  Cached queries must not be used in contexts where recursion
522  might cause the same query to be returned from this function
523  while it is being processed at another level in the execution
524  stack. Results would be undefined. Caching is primarily intended
525  for often-used routines which bind and fetch simple values, and
526  not for queries which bind large inlined values or might invoke
527  recursion. Because of the potential for recursive breakage, this
528  function flags queries it doles out and requires that clients
529  call fsl_stmt_cached_yield() to un-flag them for re-use. It will
530  return FSL_RC_ACCESS if an attempt is made to (re)prepare a
531  statement for which a fsl_stmt_cached_yield() is pending, and
532  db->error will be populated with a (long) error string
533  descripting the problem and listing the SQL which caused the
534  collision/misuse.
535 
536 
537  Design note: for the recursion/parallel use case we "could"
538  reimplement this to dole out a new statement (e.g. by appending
539  " -- a_number" to the SQL to bypass the collision) and free it in
540  fsl_stmt_cached_yield(), but that (A) gets uglier than it needs
541  to be and (B) is not needed unless/until we really need cached
542  queries in spots which would normally break them. The whole
543  recursion problem is still theoretical at this point but could
544  easily affect small, often-used queries without recursion.
545 
546  @see fsl_db_stmt_cache_clear()
547  @see fsl_stmt_cached_yield()
548 */
549 FSL_EXPORT int fsl_db_prepare_cached( fsl_db * db, fsl_stmt ** st, char const * sql, ... );
550 
551 /**
552  The va_list counterpart of fsl_db_prepare_cached().
553 */
554 FSL_EXPORT int fsl_db_preparev_cached( fsl_db * db, fsl_stmt ** st, char const * sql,
555  va_list args );
556 
557 /**
558  "Yields" a statement which was prepared with
559  fsl_db_prepare_cached(), such that that routine can once again
560  use/re-issue that statement. Statements prepared this way must
561  be yielded in order to prevent that recursion causes
562  difficult-to-track errors when a given cached statement is used
563  concurrently in different code contexts.
564 
565  If st is not NULL then this also calls fsl_stmt_reset() on the
566  statement (because that simplifies usage of cached statements).
567 
568  Returns 0 on success, FSL_RC_MISUSE if !st or if st does not
569  appear to have been doled out from fsl_db_prepare_cached().
570 
571  @see fsl_db_prepare_cached()
572  @see fsl_db_stmt_cache_clear()
573 */
575 
576 /**
577  Immediately cleans up all cached statements. Returns the number
578  of statements cleaned up. It is illegal to call this while any
579  of the cached statements are actively being used (have not been
580  fsl_stmt_cached_yield()ed), and doing so will lead to undefined
581  results if the statement(s) in question are used after this
582  function completes.
583 
584  @see fsl_db_prepare_cached()
585  @see fsl_stmt_cached_yield()
586 */
588 
589 /**
590  A special-purposes utility which schedules SQL to be executed
591  the next time fsl_db_transaction_end() commits a transaction for
592  the given db. A commit or rollback will clear all before-commit
593  SQL whether it executes them or not. This should not be used as
594  a general-purpose trick, and is intended only for use in very
595  limited parts of the Fossil infrastructure.
596 
597  Before-commit code is only executed if the db has made changes
598  since the transaction began. If no changes are recorded
599  then before-commit triggers are _not_ run. This is a historical
600  behaviour which is up for debate.
601 
602  This function does not prepare the SQL, so it does not catch
603  errors which happen at prepare-time. Preparation is done (if
604  ever) just before the next transaction is committed.
605 
606  Returns 0 on success, non-0 on error.
607 
608  Potential TODO: instead of storing the raw SQL, prepare the
609  statements here and store the statement handles. The main
610  benefit would be that this routine could report preport
611  preparation errors (which otherwise cause the the commit to
612  fail). The down-side is that it prohibits the use of
613  multi-statement pre-commit code. We have an implementation of
614  this somewhere early on in the libfossil tree, but it was not
615  integrated because of the inability to use multi-statement SQL
616  with it.
617 */
618 FSL_EXPORT int fsl_db_before_commit( fsl_db *db, char const * sql, ... );
619 
620 /**
621  va_list counterpart to fsl_db_before_commit().
622 */
623 FSL_EXPORT int fsl_db_before_commitv( fsl_db *db, char const * sql, va_list args );
624 
625 
626 /**
627  Frees memory associated with stmt but does not free stmt unless
628  it was allocated by fsl_stmt_malloc() (these objects are
629  normally stack-allocated, and such object must be initialized by
630  copying fsl_stmt_empty so that this function knows whether or
631  not to fsl_free() them). Returns FSL_RC_MISUSE if !stmt or it
632  has already been finalized (but was not freed).
633 */
635 
636 /**
637  "Steps" the given SQL cursor one time and returns one of the
638  following: FSL_RC_STEP_ROW, FSL_RC_STEP_DONE, FSL_RC_STEP_ERROR.
639  On a db error this will update the underlying db's error state.
640  This function increments stmt->rowCount by 1 if it returns
641  FSL_RC_STEP_ROW.
642 
643  Returns FSL_RC_MISUSE if !stmt or stmt has not been prepared.
644 
645  It is only legal to call the fsl_stmt_g_xxx() and
646  fsl_stmt_get_xxx() functions if this functon returns
647  FSL_RC_STEP_ROW. FSL_RC_STEP_DONE is returned upon successfully
648  ending iteration or if there is no iteration to perform (e.g. a
649  UPDATE or INSERT).
650 
651 
652  @see fsl_stmt_reset()
653  @see fsl_stmt_reset2()
654  @see fsl_stmt_each()
655 */
656 FSL_EXPORT int fsl_stmt_step( fsl_stmt * stmt );
657 
658 /**
659  A callback interface for use with fsl_stmt_each() and
660  fsl_db_each(). It will be called one time for each row fetched,
661  passed the statement object and the state parameter passed to
662  fsl_stmt_each() resp. fsl_db_each(). If it returns non-0 then
663  iteration stops and that code is returned UNLESS it returns
664  FSL_RC_BREAK, in which case fsl_stmt_each() stops iteration and
665  returns 0. i.e. implementations may return FSL_RC_BREAK to
666  prematurly end iteration without causing an error.
667 
668  This callback is not called for non-fetching queries or queries
669  which return no results, though it might (or might not) be
670  interesting for it to do so, passing a NULL stmt for that case.
671 
672  stmt->rowCount can be used to determine how many times the
673  statement has called this function. Its counting starts at 1.
674 
675  It is strictly illegal for a callback to pass stmt to
676  fsl_stmt_step(), fsl_stmt_reset(), fsl_stmt_finalize(), or any
677  similar routine which modifies its state. It must only read the
678  current column data (or similar metatdata, e.g. column names)
679  from the statement, e.g. using fsl_stmt_g_int32(),
680  fsl_stmt_get_text(), or similar.
681 */
682 typedef int (*fsl_stmt_each_f)( fsl_stmt * stmt, void * state );
683 
684 /**
685  Calls the given callback one time for each result row in the
686  given statement, iterating over stmt using fsl_stmt_step(). It
687  applies no meaning to the callbackState parameter, which gets
688  passed as-is to the callback. See fsl_stmt_each_f() for the
689  semantics of the callback.
690 
691  Returns 0 on success. Returns FSL_RC_MISUSE if !stmt or
692  !callback.
693 */
694 FSL_EXPORT int fsl_stmt_each( fsl_stmt * stmt, fsl_stmt_each_f callback,
695  void * callbackState );
696 
697 /**
698  Resets the given statement, analog to sqlite3_reset(). Should be
699  called one time between fsl_stmt_step() iterations when running
700  multiple INSERTS, UPDATES, etc. via the same statement. If
701  resetRowCounter is true then the statement's row counter
702  (st->rowCount) is also reset to 0, else it is left
703  unmodified. (Most use cases don't use the row counter.)
704 
705  Returns 0 on success, FSL_RC_MISUSE if !stmt or stmt has not
706  been prepared, FSL_RC_DB if the underlying reset fails (in which
707  case the error state of the stmt->db handle is updated to
708  contain the error information).
709 
710  @see fsl_stmt_db()
711  @see fsl_stmt_reset()
712 */
713 FSL_EXPORT int fsl_stmt_reset2( fsl_stmt * stmt, char resetRowCounter );
714 
715 /**
716  Equivalent to fsl_stmt_reset2(stmt, 0).
717 */
718 FSL_EXPORT int fsl_stmt_reset( fsl_stmt * stmt );
719 
720 /**
721  Returns the db handle which prepared the given statement, or
722  NULL if !stmt or stmt has not been prepared.
723 */
725 
726 /**
727  Returns the SQL string used to prepare the given statement, or
728  NULL if !stmt or stmt has not been prepared. If len is not NULL
729  then *len is set to the length of the returned string (which is
730  NUL-terminated). The returned bytes are owned by stmt and are
731  invalidated when it is finalized.
732 */
733 FSL_EXPORT char const * fsl_stmt_sql( fsl_stmt * stmt, fsl_size_t * len );
734 
735 /**
736  Returns the name of the given 0-based result column index, or
737  NULL if !stmt, stmt is not prepared, or index is out out of
738  range. The returned bytes are owned by the statement object and
739  may be invalidated shortly after this is called, so the caller
740  must copy the returned value if it needs to have any useful
741  lifetime guarantees. It's a bit more complicated than this, but
742  assume that any API calls involving the statement handle might
743  invalidate the column name bytes.
744 
745  The API guarantees that the returned value is either NULL or
746  NUL-terminated.
747 
748  @see fsl_stmt_param_count()
749  @see fsl_stmt_col_count()
750 */
751 FSL_EXPORT char const * fsl_stmt_col_name(fsl_stmt * stmt, int index);
752 
753 /**
754  Returns the result column count for the given statement, or -1 if
755  !stmt or it has not been prepared. Note that this value is cached
756  when the statement is created. Note that non-fetching queries
757  (e.g. INSERT and UPDATE) have a column count of 0. Some non-SELECT
758  constructs, e.g. PRAGMA table_info(tname), behave like SELECT
759  and have a positive column count.
760 
761  @see fsl_stmt_param_count()
762  @see fsl_stmt_col_name()
763 */
764 FSL_EXPORT int fsl_stmt_col_count( fsl_stmt const * stmt );
765 
766 /**
767  Returns the bound parameter count for the given statement, or -1
768  if !stmt or it has not been prepared. Note that this value is
769  cached when the statement is created.
770 
771  @see fsl_stmt_col_count()
772  @see fsl_stmt_col_name()
773 */
774 FSL_EXPORT int fsl_stmt_param_count( fsl_stmt const * stmt );
775 
776 /**
777  Returns the index of the given named parameter for the given
778  statement, or -1 if !stmt or stmt is not prepared.
779 */
780 FSL_EXPORT int fsl_stmt_param_index( fsl_stmt * stmt, char const * param);
781 
782 /**
783  Binds NULL to the given 1-based parameter index. Returns 0 on
784  succcess. Sets the DB's error state on error.
785 */
786 FSL_EXPORT int fsl_stmt_bind_null( fsl_stmt * stmt, int index );
787 
788 /**
789  Equivalent to fsl_stmt_bind_null_name() but binds to
790  a named parameter.
791 */
792 FSL_EXPORT int fsl_stmt_bind_null_name( fsl_stmt * stmt, char const * param );
793 
794 /**
795  Binds v to the given 1-based parameter index. Returns 0 on
796  succcess. Sets the DB's error state on error.
797 */
798 FSL_EXPORT int fsl_stmt_bind_int32( fsl_stmt * stmt, int index, fsl_int32_t v );
799 
800 /**
801  Equivalent to fsl_stmt_bind_int32() but binds to a named
802  parameter.
803 */
804 FSL_EXPORT int fsl_stmt_bind_int32_name( fsl_stmt * stmt, char const * param, fsl_int32_t v );
805 
806 /**
807  Binds v to the given 1-based parameter index. Returns 0 on
808  succcess. Sets the DB's error state on error.
809 */
810 FSL_EXPORT int fsl_stmt_bind_int64( fsl_stmt * stmt, int index, fsl_int64_t v );
811 
812 /**
813  Equivalent to fsl_stmt_bind_int64() but binds to a named
814  parameter.
815 */
816 FSL_EXPORT int fsl_stmt_bind_int64_name( fsl_stmt * stmt, char const * param, fsl_int64_t v );
817 
818 /**
819  Binds v to the given 1-based parameter index. Returns 0 on
820  succcess. Sets the Fossil context's error state on error.
821 */
822 FSL_EXPORT int fsl_stmt_bind_double( fsl_stmt * stmt, int index, fsl_double_t v );
823 
824 /**
825  Equivalent to fsl_stmt_bind_double() but binds to a named
826  parameter.
827 */
828 FSL_EXPORT int fsl_stmt_bind_double_name( fsl_stmt * stmt, char const * param, fsl_double_t v );
829 
830 /**
831  Binds v to the given 1-based parameter index. Returns 0 on
832  succcess. Sets the DB's error state on error.
833 */
834 FSL_EXPORT int fsl_stmt_bind_id( fsl_stmt * stmt, int index, fsl_id_t v );
835 
836 /**
837  Equivalent to fsl_stmt_bind_id() but binds to a named
838  parameter.
839 */
840 FSL_EXPORT int fsl_stmt_bind_id_name( fsl_stmt * stmt, char const * param, fsl_id_t v );
841 
842 /**
843  Binds the first n bytes of v as text to the given 1-based bound
844  parameter column in the given statement. If makeCopy is true then
845  the binding makes an copy of the data. Set makeCopy to false ONLY
846  if you KNOW that the bytes will outlive the binding.
847 
848  Returns 0 on success. On error stmt's underlying db's error state
849  is updated, hopefully with a useful error message.
850 */
851 FSL_EXPORT int fsl_stmt_bind_text( fsl_stmt * stmt, int index,
852  char const * v, fsl_int_t n,
853  char makeCopy );
854 
855 /**
856  Equivalent to fsl_stmt_bind_text() but binds to a named
857  parameter.
858 */
859 FSL_EXPORT int fsl_stmt_bind_text_name( fsl_stmt * stmt, char const * param,
860  char const * v, fsl_int_t n,
861  char makeCopy );
862 /**
863  Binds the first n bytes of v as a blob to the given 1-based bound
864  parameter column in the given statement. See fsl_stmt_bind_text()
865  for the semantics of the makeCopy parameter and return value.
866 */
867 FSL_EXPORT int fsl_stmt_bind_blob( fsl_stmt * stmt, int index,
868  void const * v, fsl_size_t len,
869  char makeCopy );
870 
871 /**
872  Equivalent to fsl_stmt_bind_blob() but binds to a named
873  parameter.
874 */
875 FSL_EXPORT int fsl_stmt_bind_blob_name( fsl_stmt * stmt, char const * param,
876  void const * v, fsl_int_t len,
877  char makeCopy );
878 
879 /**
880  Gets an integer value from the given 0-based result set column,
881  assigns *v to that value, and returns 0 on success.
882 
883  Returns FSL_RC_RANGE if index is out of range for stmt.
884 */
885 FSL_EXPORT int fsl_stmt_get_int32( fsl_stmt * stmt, int index, fsl_int32_t * v );
886 
887 /**
888  Gets an integer value from the given 0-based result set column,
889  assigns *v to that value, and returns 0 on success.
890 
891  Returns FSL_RC_RANGE if index is out of range for stmt.
892 */
893 FSL_EXPORT int fsl_stmt_get_int64( fsl_stmt * stmt, int index, fsl_int64_t * v );
894 
895 /**
896  The fsl_id_t counterpart of fsl_stmt_get_int32(). Depending on
897  the sizeof(fsl_id_t), it behaves as one of fsl_stmt_get_int32()
898  or fsl_stmt_get_int64().
899 */
900 FSL_EXPORT int fsl_stmt_get_id( fsl_stmt * stmt, int index, fsl_id_t * v );
901 
902 /**
903  Convenience form of fsl_stmt_get_id() which returns the value
904  directly but cannot report errors. It returns -1 on error, but
905  that is not unambiguously an error value.
906 */
907 FSL_EXPORT fsl_id_t fsl_stmt_g_id( fsl_stmt * stmt, int index );
908 
909 /**
910  Convenience form of fsl_stmt_get_int32() which returns the value
911  directly but cannot report errors. It returns 0 on error, but
912  that is not unambiguously an error.
913 */
914 FSL_EXPORT fsl_int32_t fsl_stmt_g_int32( fsl_stmt * stmt, int index );
915 
916 /**
917  Convenience form of fsl_stmt_get_int64() which returns the value
918  directly but cannot report errors. It returns 0 on error, but
919  that is not unambiguously an error.
920 */
921 FSL_EXPORT fsl_int64_t fsl_stmt_g_int64( fsl_stmt * stmt, int index );
922 
923 /**
924  Convenience form of fsl_stmt_get_double() which returns the value
925  directly but cannot report errors. It returns 0 on error, but
926  that is not unambiguously an error.
927 */
929 
930 /**
931  Convenience form of fsl_stmt_get_text() which returns the value
932  directly but cannot report errors. It returns NULL on error, but
933  that is not unambiguously an error because it also returns NULL
934  if the column contains an SQL NULL value. If outLen is not NULL
935  then it is set to the byte length of the returned string.
936 */
937 FSL_EXPORT char const * fsl_stmt_g_text( fsl_stmt * stmt, int index, fsl_size_t * outLen );
938 
939 /**
940  Gets double value from the given 0-based result set column,
941  assigns *v to that value, and returns 0 on success.
942 
943  Returns FSL_RC_RANGE if index is out of range for stmt.
944 */
945 FSL_EXPORT int fsl_stmt_get_double( fsl_stmt * stmt, int index, fsl_double_t * v );
946 
947 /**
948  Gets a string value from the given 0-based result set column,
949  assigns *out (if out is not NULL) to that value, assigns *outLen
950  (if outLen is not NULL) to *out's length in bytes, and returns 0
951  on success. Ownership of the string memory is unchanged - it is owned
952  by the statement and the caller should immediately copy it if
953  it will be needed for much longer.
954 
955  Returns FSL_RC_RANGE if index is out of range for stmt.
956 */
957 FSL_EXPORT int fsl_stmt_get_text( fsl_stmt * stmt, int index, char const **out,
958  fsl_size_t * outLen );
959 
960 /**
961  The Blob counterpart of fsl_stmt_get_text(). Identical to that
962  function except that its output result (3rd paramter) type
963  differs, and it fetches the data as a raw blob, without any sort
964  of string interpretation.
965 
966  Returns FSL_RC_RANGE if index is out of range for stmt.
967 */
968 FSL_EXPORT int fsl_stmt_get_blob( fsl_stmt * stmt, int index, void const **out, fsl_size_t * outLen );
969 
970 /**
971  Executes multiple SQL statements, ignoring any results they might
972  collect. Returns 0 on success, non-0 on error. On error
973  db->error might be updated to report the problem.
974 */
975 FSL_EXPORT int fsl_db_exec_multi( fsl_db * db, const char * sql, ...);
976 
977 /**
978  va_list counterpart of db_exec_multi().
979 */
980 FSL_EXPORT int fsl_db_exec_multiv( fsl_db * db, const char * sql, va_list args);
981 
982 /**
983  Executes a single SQL statement, skipping over any results
984  it may have. Returns 0 on success. On error db's error state
985  may be updated.
986 */
987 FSL_EXPORT int fsl_db_exec( fsl_db * db, char const * sql, ... );
988 
989 /**
990  va_list counterpart of fs_db_exec().
991 */
992 FSL_EXPORT int fsl_db_execv( fsl_db * db, char const * sql, va_list args );
993 
994 /**
995  Begins a transaction on the given db. Nested transactions are
996  not directly supported but the db handle keeps track of
997  open/close counts, such that fsl_db_transaction_end() will not
998  actually do anything until the transaction begin/end counter
999  goes to 0. Returns FSL_RC_MISUSE if !db or the db is not
1000  connected, else the result of the underlying db call(s).
1001 
1002  Transactions are an easy way to implement "dry-run" mode for
1003  some types of applications. For example:
1004 
1005  @code
1006  char dryRunMode = ...;
1007  fsl_db_transaction_begin(db);
1008  ...do your stuff...
1009  fsl_db_transaction_end(db, dryRunMode ? 1 : 0);
1010  @endcode
1011 
1012  Here's a tip for propagating error codes when using
1013  transactions:
1014 
1015  @code
1016  ...
1017  if(rc) fsl_db_transaction_end(db, 1);
1018  else rc = fsl_db_transaction_end(db, 0);
1019  @endcode
1020 
1021  That ensures that we propagate rc in the face of a rollback but
1022  we also capture the rc for a commit (which might yet fail). Note
1023  that a rollback in and of itself is not an error (though it also
1024  might fail, that would be "highly unusual" and indicative of
1025  other problems), and we certainly don't want to overwrite that
1026  precious non-0 rc with a successful return result from a
1027  rollback (which would, in effect, hide the error from the
1028  client).
1029 */
1031 
1032 /**
1033  Equivalent to fsl_db_transaction_end(db, 0).
1034 */
1036 
1037 /**
1038  Equivalent to fsl_db_transaction_end(db, 1).
1039 */
1041 
1042 /**
1043  Forces a rollback of any pending transaction in db, regardless
1044  of the internal transaction begin/end counter. Returns
1045  FSL_RC_MISUSE if !db or db is not opened, else returns the value
1046  of the underlying ROLLBACK call. This also re-sets/frees any
1047  transaction-related state held by db (e.g. db->beforeCommit).
1048  Use with care, as this mucks about with db state in a way which
1049  is not all that pretty and it may confuse downstream code.
1050 
1051  Returns 0 on success.
1052 */
1054 
1055 /**
1056  Decrements the transaction counter incremented by
1057  fsl_db_transaction_begin() and commits or rolls back the
1058  transaction if the counter goes to 0.
1059 
1060  If doRollback is true then this rolls back (or schedules a
1061  rollback of) a transaction started by
1062  fsl_db_transaction_begin(). If doRollback is false is commits
1063  (or schedules a commit).
1064 
1065  If db fsl_db_transaction_begin() is used in a nested manner and
1066  doRollback is true for any one of the nested calls, then that
1067  value will be remembered, such that the downstream calls to this
1068  function within the same transaction will behave like a rollback
1069  even if they pass 0 for the second argument.
1070 
1071  Returns FSL_RC_MISUSE if !db or the db is not opened, 0 if
1072  the transaction counter is above 0, else the result of the
1073  (potentially many) underlying database operations.
1074 
1075  Unfortunate low-level co-dependency: if db->f is not NULL and
1076  (db->role & FSL_DB_ROLE_REPO) then this function may perform
1077  extra repository-related post-processing on any commit, and
1078  checking the result code is particularly important for those
1079  cases.
1080 */
1081 FSL_EXPORT int fsl_db_transaction_end(fsl_db * db, char doRollback);
1082 
1083 /**
1084  Runs the given SQL query on the given db and returns non-0
1085  (true) if the query returns any rows, else 0 (false). Returns 0
1086  for any error as well.
1087 */
1088 FSL_EXPORT char fsl_db_exists(fsl_db * db, char const * sql, ... );
1089 
1090 /**
1091  va_list counterpart of fsl_db_exists().
1092 */
1093 FSL_EXPORT char fsl_db_existsv(fsl_db * db, char const * sql, va_list args );
1094 
1095 /**
1096  Runs a fetch-style SQL query against DB and returns the first
1097  column of the first result row via *rv. If the query returns no
1098  rows, *rv is not modified. The intention is that the caller sets
1099  *rv to his preferred default (or sentinel) value before calling
1100  this.
1101 
1102  The format string (the sql parameter) accepts all formatting
1103  options supported by fsl_appendf().
1104 
1105  Returns 0 on success. On error db's error state is updated and
1106  *rv is not modified.
1107 
1108  Returns FSL_RC_MISUSE without side effects if !db, !rv, !sql,
1109  or !*sql.
1110 */
1112  char const * sql, ... );
1113 
1114 /**
1115  va_list counterpart of fsl_db_get_int32().
1116 */
1118  char const * sql, va_list args);
1119 
1120 /**
1121  Convenience form of fsl_db_get_int32() which returns the value
1122  directly but provides no way of checking for errors. On error,
1123  or if no result is found, defaultValue is returned.
1124 */
1126  char const * sql, ... );
1127 
1128 /**
1129  The int64 counterpart of fsl_db_get_int32(). See that function
1130  for the semantics.
1131 */
1133  char const * sql, ... );
1134 
1135 /**
1136  va_list counterpart of fsl_db_get_int64().
1137 */
1139  char const * sql, va_list args);
1140 
1141 /**
1142  Convenience form of fsl_db_get_int64() which returns the value
1143  directly but provides no way of checking for errors. On error,
1144  or if no result is found, defaultValue is returned.
1145 */
1147  char const * sql, ... );
1148 
1149 
1150 /**
1151  The fsl_id_t counterpart of fsl_db_get_int32(). See that function
1152  for the semantics.
1153 */
1154 FSL_EXPORT int fsl_db_get_id( fsl_db * db, fsl_id_t * rv,
1155  char const * sql, ... );
1156 
1157 /**
1158  va_list counterpart of fsl_db_get_id().
1159 */
1160 FSL_EXPORT int fsl_db_get_idv( fsl_db * db, fsl_id_t * rv,
1161  char const * sql, va_list args);
1162 
1163 /**
1164  Convenience form of fsl_db_get_id() which returns the value
1165  directly but provides no way of checking for errors. On error,
1166  or if no result is found, defaultValue is returned.
1167 */
1168 FSL_EXPORT fsl_id_t fsl_db_g_id( fsl_db * db, fsl_id_t defaultValue,
1169  char const * sql, ... );
1170 
1171 
1172 /**
1173  The fsl_size_t counterpart of fsl_db_get_int32(). See that
1174  function for the semantics. If this function would fetch a
1175  negative value, it returns FSL_RC_RANGE and *rv is not modified.
1176 */
1178  char const * sql, ... );
1179 
1180 /**
1181  va_list counterpart of fsl_db_get_size().
1182 */
1184  char const * sql, va_list args);
1185 
1186 /**
1187  Convenience form of fsl_db_get_size() which returns the value
1188  directly but provides no way of checking for errors. On error,
1189  or if no result is found, defaultValue is returned.
1190 */
1192  char const * sql, ... );
1193 
1194 
1195 /**
1196  The double counterpart of fsl_db_get_int32(). See that function
1197  for the semantics.
1198 */
1200  char const * sql, ... );
1201 
1202 /**
1203  va_list counterpart of fsl_db_get_double().
1204 */
1206  char const * sql, va_list args);
1207 
1208 /**
1209  Convenience form of fsl_db_get_double() which returns the value
1210  directly but provides no way of checking for errors. On error,
1211  or if no result is found, defaultValue is returned.
1212 */
1214  char const * sql, ... );
1215 
1216 /**
1217  The C-string counterpart of fsl_db_get_int32(). On success *rv
1218  will be set to a dynamically allocated string copied from the
1219  first column of the first result row. If rvLen is not NULL then
1220  *rvLen will be assigned the byte-length of that string. If no
1221  row is found, *rv is set to NULL and *rvLen (if not NULL) is set
1222  to 0, and 0 is returned. Note that NULL is also a legal result
1223  (an SQL NULL translates as a NULL string), The caller must
1224  eventually free the returned string value using fsl_free().
1225 */
1226 FSL_EXPORT int fsl_db_get_text( fsl_db * db, char ** rv, fsl_size_t * rvLen,
1227  char const * sql, ... );
1228 
1229 /**
1230  va_list counterpart of fsl_db_get_text().
1231 */
1232 FSL_EXPORT int fsl_db_get_textv( fsl_db * db, char ** rv, fsl_size_t * rvLen,
1233  char const * sql, va_list args );
1234 
1235 /**
1236  Convenience form of fsl_db_get_text() which returns the value
1237  directly but provides no way of checking for errors. On error,
1238  or if no result is found, NULL is returned. The returned string
1239  must eventually be passed to fsl_free() to free it. If len is
1240  not NULL then if non-NULL is returned, *len will be assigned the
1241  byte-length of the returned string.
1242 */
1243 FSL_EXPORT char * fsl_db_g_text( fsl_db * db, fsl_size_t * len,
1244  char const * sql,
1245  ... );
1246 
1247 /**
1248  The Blob counterpart of fsl_db_get_text(). Identical to that
1249  function except that its output result (2nd paramter) type
1250  differs, and it fetches the data as a raw blob, without any sort
1251  of string interpretation. The returned *rv memory must
1252  eventually be passed to fsl_free() to free it. If len is not
1253  NULL then on success *len will be set to the byte length of the
1254  returned blob. If no row is found, *rv is set to NULL and *rvLen
1255  (if not NULL) is set to 0, and 0 is returned. Note that NULL is
1256  also a legal result (an SQL NULL translates as a NULL string),
1257 */
1258 FSL_EXPORT int fsl_db_get_blob( fsl_db * db, void ** rv, fsl_size_t * len,
1259  char const * sql, ... );
1260 
1261 
1262 /**
1263  va_list counterpart of fsl_db_get_blob().
1264 */
1265 FSL_EXPORT int fsl_db_get_blobv( fsl_db * db, void ** rv, fsl_size_t * stmtLen,
1266  char const * sql, va_list args );
1267 
1268 /**
1269  Convenience form of fsl_db_get_blob() which returns the value
1270  directly but provides no way of checking for errors. On error,
1271  or if no result is found, NULL is returned.
1272 */
1273 FSL_EXPORT void * fsl_db_g_blob( fsl_db * db, fsl_size_t * len,
1274  char const * sql,
1275  ... );
1276 /**
1277  Similar to fsl_db_get_text() and fsl_db_get_blob(), but writes
1278  its result to tgt, overwriting (not appennding to) any existing
1279  memory it might hold.
1280 
1281  If asBlob is true then the underlying BLOB API is used to
1282  populate the buffer, else the underlying STRING/TEXT API is
1283  used. For many purposes there will be no difference, but if you
1284  know you might have binary data, be sure to pass a true value
1285  for asBlob to avoid any potential encoding-related problems.
1286 */
1288  char asBlob,
1289  char const * sql, ... );
1290 
1291 /**
1292  va_list counterpart of fsl_db_get_buffer().
1293 */
1295  char asBlob,
1296  char const * sql, va_list args );
1297 
1298 
1299 /**
1300  Expects sql to be a SELECT-style query which (potentially)
1301  returns a result set. For each row in the set callback() is
1302  called, as described for fsl_stmt_each(). Returns 0 on success.
1303  The callback is _not_ called for queries which return no
1304  rows. If clients need to know if rows were returned, they can
1305  add a counter to their callbackState and increment it from the
1306  callback.
1307 
1308  Returns FSL_RC_MISUSE if !db, db is not opened, !callback,
1309  !sql. Returns FSL_RC_RANGE if !*sql.
1310 */
1311 FSL_EXPORT int fsl_db_each( fsl_db * db, fsl_stmt_each_f callback,
1312  void * callbackState, char const * sql, ... );
1313 
1314 /**
1315  va_list counterpart to fsl_db_each().
1316 */
1317 FSL_EXPORT int fsl_db_eachv( fsl_db * db, fsl_stmt_each_f callback,
1318  void * callbackState, char const * sql, va_list args );
1319 
1320 
1321 /**
1322  Returns the given Julian date value formatted as an ISO8601
1323  string (with a fractional seconds part if msPrecision is true,
1324  else without it). Returns NULL if !db, db is not connected, j
1325  is less than 0, or on allocation error. The returned memory must
1326  eventually be freed using fsl_free().
1327 
1328  If localTime is true then the value is converted to the local time,
1329  otherwise it is not.
1330 
1331  @see fsl_db_unix_to_iso8601()
1332  @see fsl_julian_to_iso8601()
1333  @see fsl_iso8601_to_julian()
1334 */
1336  char msPrecision, char localTime );
1337 
1338 /**
1339  Returns the given Julian date value formatted as an ISO8601
1340  string (with a fractional seconds part if msPrecision is true,
1341  else without it). Returns NULL if !db, db is not connected, j
1342  is less than 0, or on allocation error. The returned memory must
1343  eventually be freed using fsl_free().
1344 
1345  If localTime is true then the value is converted to the local time,
1346  otherwise it is not.
1347 
1348  @see fsl_db_julian_to_iso8601()
1349  @see fsl_julian_to_iso8601()
1350  @see fsl_iso8601_to_julian()
1351 */
1352 FSL_EXPORT char * fsl_db_unix_to_iso8601( fsl_db * db, fsl_time_t j, char localTime );
1353 
1354 
1355 /**
1356  Returns the current time in Julian Date format. Returns a negative
1357  value if !db or db is not opened.
1358 */
1360 
1361 /**
1362  Uses the given db to convert the given time string to Julian Day
1363  format. If it cannot be converted, a negative value is returned.
1364  The str parameter can be anything suitable for passing to sqlite's:
1365 
1366  SELECT julianday(str)
1367 
1368  Note that this routine will escape str for use with SQL - the
1369  caller must not do so.
1370 
1371  @see fsl_julian_to_iso8601()
1372  @see fsl_iso8601_to_julian()
1373 */
1374 FSL_EXPORT fsl_double_t fsl_db_string_to_julian(fsl_db * db, char const * str);
1375 
1376 /**
1377  Opens the given db file and populates db with its handle. db
1378  must have been cleanly initialized by copy-initializing it from
1379  fsl_db_empty (or fsl_db_empty_m) or by allocating it using
1380  fsl_db_malloc(). Failure to do so will lead to undefined
1381  behaviour.
1382 
1383  openFlags may be a mask of FSL_OPEN_F_xxx values, but not all
1384  are used/supported here. If FSL_OPEN_F_CREATE is _not_ set in
1385  openFlags and dbFile does not exist, it will return
1386  FSL_RC_NOT_FOUND. The existence of FSL_OPEN_F_CREATE in the
1387  flags will cause this routine to try to create the file if
1388  needed. If conflicting flags are specified (e.g. FSL_OPEN_F_RO
1389  and FSL_OPEN_F_RWC) then which one takes precedence is
1390  unspecified and possibly unpredictable.
1391 
1392  As a special case, if dbFile is ":memory:" (for an in-memory
1393  database) or "" (empty string, for a "temporary" database) then it
1394  is is passed through without any filesystem-related checks and the
1395  openFlags are ignored.
1396 
1397  See this page for the differences between ":memory:" and "":
1398 
1399  https://www.sqlite.org/inmemorydb.html
1400 
1401  Returns FSL_RC_MISUSE if !db, !dbFile, !*dbFile, or if db->dbh
1402  is not NULL (i.e. if it is already opened or its memory was
1403  default-initialized (use fsl_db_empty to cleanly copy-initialize
1404  new stack-allocated instances).
1405 
1406  On error db->dbh will be NULL, but db->error might contain error
1407  details.
1408 
1409  Regardless of success or failure, db should be passed to
1410  fsl_db_close() to free up all memory associated with it. It is
1411  not closed automatically by this function because doing so cleans
1412  up the error state, which the caller will presumably want to
1413  have.
1414 
1415  If db->f is not NULL when this is called then it is assumed that
1416  db should be plugged in to the Fossil repository system, and the
1417  following additional things happen:
1418 
1419  - A number of SQL functions are registered with the db. Details
1420  are below.
1421 
1422  - If FSL_OPEN_F_SCHEMA_VALIDATE is set in openFlags then the
1423  db is validated to see if it has a fossil schema. If that
1424  validation fails, FSL_RC_REPO_NEEDS_REBUILD or FSL_RC_NOT_A_REPO
1425  will be returned and db's error state will be updated. db->f
1426  does not need to be set for that check to work.
1427 
1428 
1429  The following SQL functions get registered with the db if db->f
1430  is not NULL when this function is called:
1431 
1432  - NOW() returns the current time as an integer, as per time(2).
1433 
1434  - FSL_USER() returns the current value of fsl_cx_user_get(),
1435  or NULL if that is not set.
1436 
1437  - FSL_CONTENT(INTEGER|STRING) returns the undeltified,
1438  uncompressed content for the blob record with the given ID (if
1439  the argument is an integer) or symbolic name (as per
1440  fsl_sym_to_rid()), as per fsl_content_get(). If the argument
1441  does not resolve to an in-repo blob, a db-level error is
1442  triggered. If passed an integer, no validation is done on its
1443  validity, but such checking can be enforced by instead passing
1444  the the ID as a string in the form "rid:ID". Both cases will
1445  result in an error if the RID is not found, but the error
1446  reporting is arguably slightly better for the "rid:ID" case.
1447 
1448  - FSL_SYM2RID(STRING) returns a blob RID for the given symbol,
1449  as per fsl_sym_to_rid(). Triggers an SQL error if fsl_sym_to_rid()
1450  fails.
1451 
1452  - FSL_DIRPART(STRING[, BOOL=0]) behaves like fsl_file_dirpart(),
1453  returning the result as a string unless it is empty, in which case
1454  the result is an SQL NULL.
1455 
1456  Note that functions described as "triggering a db error" will
1457  propagate that error, such that fsl_db_err_get() can report it
1458  to the client.
1459 
1460 
1461  @see fsl_db_close()
1462  @see fsl_db_prepare()
1463  @see fsl_db_malloc()
1464 */
1465 FSL_EXPORT int fsl_db_open( fsl_db * db, char const * dbFile, int openFlags );
1466 
1467 /**
1468  Closes the given db handle and frees any resources owned by
1469  db. Returns 0 on success.
1470 
1471  If db was allocated using fsl_db_malloc() (as determined by
1472  examining db->allocStamp) then this routine also fsl_free()s it,
1473  otherwise it is assumed to either be on the stack or part of a
1474  larger struct and is not freed.
1475 
1476  If db has any pending transactions, they are rolled
1477  back by this function.
1478 */
1479 FSL_EXPORT int fsl_db_close( fsl_db * db );
1480 
1481 /**
1482  If db is an opened db handle, this registers a debugging
1483  function with the db which traces all SQL to the given FILE
1484  handle (defaults to stdout if outStream is NULL).
1485 
1486  This mechanism is only intended for debugging and exploration of
1487  how Fossil works. Tracing is often as easy way to ensure that a
1488  given code block is getting run.
1489 
1490  As a special case, if db->f is not NULL _before_ it is is
1491  fsl_db_open()ed, then this function automatically gets installed
1492  if the SQL tracing option is enabled for that fsl_cx instance
1493  before the db is opened.
1494 
1495  This is a no-op if !db or db is not opened.
1496 */
1497 FSL_EXPORT void fsl_db_sqltrace_enable( fsl_db * db, FILE * outStream );
1498 
1499 /**
1500  Returns the row ID of the most recent insertion,
1501  or -1 if !db, db is not connected, or 0 if no inserts
1502  have been performed.
1503 */
1505 
1506 /**
1507  Returns non-0 (true) if the database (which must be open) table
1508  identified by zTableName has a column named zColName
1509  (case-sensitive), else returns 0.
1510 */
1511 FSL_EXPORT char fsl_db_table_has_column( fsl_db * db, char const *zTableName,
1512  char const *zColName );
1513 
1514 /**
1515  If a db name has been associated with db then it is returned,
1516  otherwise NULL is returned. A db has no name by default, but
1517  fsl_cx-used ones get their database name assigned to them
1518  (e.g. "main" for the main db).
1519 */
1520 FSL_EXPORT char const * fsl_db_name(fsl_db const * db);
1521 
1522 
1523 /**
1524  Returns a db name string for the given fsl_db_role value. The
1525  string is static, guaranteed to live as long as the app. It
1526  returns NULL (or asserts in debug builds) if passed
1527  FSL_DB_ROLE_NONE or some value out of range for the enum.
1528 */
1529 FSL_EXPORT const char * fsl_db_role_label(enum fsl_db_role_t r);
1530 
1531 
1532 /**
1533  Allocates a new fsl_db instance(). Returns NULL on allocation
1534  error. Note that fsl_db instances can often be used from the
1535  stack - allocating them dynamically is an uncommon case necessary
1536  for script bindings.
1537 
1538  Achtung: the returned value's allocStamp member is used for
1539  determining if fsl_db_close() should free the value or not. Thus
1540  if clients copy over this value without adjusting allocStamp back
1541  to its original value, the library will likely leak the instance.
1542  Been there, done that.
1543 */
1545 
1546 /**
1547  The fsl_stmt counterpart of fsl_db_malloc(). See that function
1548  for when you might want to use this and a caveat involving the
1549  allocStamp member of the returned value. fsl_stmt_finalize() will
1550  free statements created with this function.
1551 */
1553 
1554 
1555 /**
1556  ATTACHes the file zDbName to db using the databbase name
1557  zLabel. Returns 0 on success. Returns FSL_RC_MISUSE if any
1558  argument is NULL or any string argument starts with a NUL byte,
1559  else it returns the result of fsl_db_exec() which attaches the
1560  db. On db-level errors db's error state will be updated.
1561 */
1562 FSL_EXPORT int fsl_db_attach(fsl_db * db, const char *zDbName, const char *zLabel);
1563 
1564 /**
1565  The converse of fsl_db_detach(). Must be passed the same arguments
1566  which were passed as the 1st and 3rd arguments to fsl_db_attach().
1567  Returns 0 on success, FSL_RC_MISUSE if !db, !zLabel, or !*zLabel,
1568  else it returns the result of the underlying fsl_db_exec()
1569  call.
1570 */
1571 FSL_EXPORT int fsl_db_detach(fsl_db * db, const char *zLabel);
1572 
1573 
1574 /**
1575  Expects fmt to be a SELECT-style query. For each row in the
1576  query, the first column is fetched as a string and appended to
1577  the tgt list.
1578 
1579  Returns 0 on success, FSL_RC_MISUSE if !db, !tgt, or !fmt, any
1580  number of potential FSL_RC_OOM or db-related errors.
1581 
1582  Results rows with a NULL value (resulting from an SQL NULL) are
1583  added to the list as NULL entries.
1584 
1585  Each entry appended to the list is a (char *) which must
1586  be freed using fsl_free(). To easiest way to clean up
1587  the list and its contents is:
1588 
1589  @code
1590  fsl_list_visit_free(tgt);
1591  @endcode
1592 
1593  On error the list may be partially populated.
1594 
1595  Complete example:
1596  @code
1597  fsl_list li = fsl_list_empty;
1598  int rc = fsl_db_select_slist(db, &li,
1599  "SELECT uuid FROM blob WHERE rid<20");
1600  if(!rc){
1601  fsl_size_t i;
1602  for(i = 0;i < li.used; ++i){
1603  char const * uuid = (char const *)li.list[i];
1604  fsl_fprintf(stdout, "UUID: %s\n", uuid);
1605  }
1606  }
1607  fsl_list_visit_free(&li, 1);
1608  @endcode
1609 
1610  Of course fsl_list_visit() may be used to traverse the list as
1611  well, as long as the visitor expects (char [const]*) list
1612  elements.
1613 */
1615  char const * fmt, ... );
1616 
1617 /**
1618  The va_list counterpart of fsl_db_select_slist().
1619 */
1621  char const * fmt, va_list args );
1622 
1623 /**
1624  Returns n bytes of random lower-case hexidecimal characters
1625  using the given db as its data source, plus a terminating NUL
1626  byte. The returned memory must eventually be freed using
1627  fsl_free(). Returns NULL if !db, !n, or on a db-level error.
1628 */
1630 
1631 /**
1632  Returns the "number of database rows that were changed or
1633  inserted or deleted by the most recently completed SQL statement"
1634  (to quote the underlying APIs). Returns 0 if !db or if db is not
1635  opened.
1636 
1637 
1638  See: http://sqlite.org/c3ref/changes.html
1639 */
1641 
1642 /**
1643  Returns "the number of row changes caused by INSERT, UPDATE or
1644  DELETE statements since the database connection was opened" (to
1645  quote the underlying APIs). Returns 0 if !db or if db is not
1646  opened.
1647 
1648  See; http://sqlite.org/c3ref/total_changes.html
1649 */
1651 
1652 /**
1653  Initializes the given database file. zFilename is the name of
1654  the db file. It is created if needed, but any directory
1655  components are not created. zSchema is the base schema to
1656  install. The following arguments may be (char const *) SQL
1657  code, each of which gets run against the db after the main
1658  schema is called. The variadic argument list MUST end with NULL
1659  (0), even if there are no non-NULL entries.
1660 
1661  Returns 0 on success.
1662 
1663  On error, if err is not NULL then it is populated with any error
1664  state from the underlying (temporary) db handle.
1665 */
1666 FSL_EXPORT int fsl_db_init( fsl_error * err, char const * zFilename,
1667  char const * zSchema, ... );
1668 
1669 /**
1670  A fsl_stmt_each_f() impl, intended primarily for debugging, which
1671  simply outputs row data in tabular form via fsl_output(). The
1672  state argument is ignored. This only works if stmt was prepared
1673  by a fsl_db instance which has an associated fsl_cx instance. On
1674  the first row, the column names are output.
1675 */
1676 FSL_EXPORT int fsl_stmt_each_f_dump( fsl_stmt * stmt, void * state );
1677 
1678 
1679 #if defined(__cplusplus)
1680 } /*extern "C"*/
1681 #endif
1682 #endif
1683 /* NET_FOSSIL_SCM_FSL_DB_H_INCLUDED */
fsl_uint_t fsl_size_t
fsl_size_t is an unsigned integer type used to denote absolute ranges and lengths.
fsl_stmt * next
For _internal_ use in creating linked lists.
Definition: fossil-db.h:368
int fsl_int32_t
Definition: fossil-config.h:81
FSL_EXPORT fsl_db * fsl_stmt_db(fsl_stmt *stmt)
Returns the db handle which prepared the given statement, or NULL if !stmt or stmt has not been prepa...
fsl_stmt_t * stmt
Underlying db driver-level statement handle.
Definition: fossil-db.h:332
FSL_EXPORT int fsl_db_exec_multi(fsl_db *db, const char *sql,...)
Executes multiple SQL statements, ignoring any results they might collect.
FSL_EXPORT int fsl_stmt_param_index(fsl_stmt *stmt, char const *param)
Returns the index of the given named parameter for the given statement, or -1 if !stmt or stmt is not...
The main Fossil "context" type.
FSL_EXPORT int fsl_db_get_idv(fsl_db *db, fsl_id_t *rv, char const *sql, va_list args)
va_list counterpart of fsl_db_get_id().
FSL_EXPORT int fsl_db_changes_recent(fsl_db *db)
Returns the "number of database rows that were changed or inserted or deleted by the most recently co...
FSL_EXPORT int fsl_stmt_get_double(fsl_stmt *stmt, int index, fsl_double_t *v)
Gets double value from the given 0-based result set column, assigns *v to that value, and returns 0 on success.
FSL_EXPORT int fsl_db_changes_total(fsl_db *db)
Returns "the number of row changes caused by INSERT, UPDATE or DELETE statements since the database c...
FSL_EXPORT int fsl_db_execv(fsl_db *db, char const *sql, va_list args)
va_list counterpart of fs_db_exec().
fsl_int64_t fsl_time_t
The type used to represent type values.
FSL_EXPORT int fsl_db_get_text(fsl_db *db, char **rv, fsl_size_t *rvLen, char const *sql,...)
The C-string counterpart of fsl_db_get_int32().
FSL_EXPORT int fsl_db_prepare_cached(fsl_db *db, fsl_stmt **st, char const *sql,...)
A special-purpose variant of fsl_db_prepare() which caches statements based on their SQL code...
FSL_EXPORT int fsl_stmt_get_id(fsl_stmt *stmt, int index, fsl_id_t *v)
The fsl_id_t counterpart of fsl_stmt_get_int32().
FSL_EXPORT int fsl_stmt_bind_id_name(fsl_stmt *stmt, char const *param, fsl_id_t v)
Equivalent to fsl_stmt_bind_id() but binds to a named parameter.
sqlite3_stmt fsl_stmt_t
Definition: fossil-db.h:258
FSL_EXPORT int fsl_stmt_bind_text_name(fsl_stmt *stmt, char const *param, char const *v, fsl_int_t n, char makeCopy)
Equivalent to fsl_stmt_bind_text() but binds to a named parameter.
FSL_EXPORT fsl_int32_t fsl_db_g_int32(fsl_db *db, fsl_int32_t defaultValue, char const *sql,...)
Convenience form of fsl_db_get_int32() which returns the value directly but provides no way of checki...
FSL_EXPORT char const * fsl_stmt_col_name(fsl_stmt *stmt, int index)
Returns the name of the given 0-based result column index, or NULL if !stmt, stmt is not prepared...
void const * allocStamp
A marker which tells fsl_stmt_finalize() whether or not fsl_stmt_malloc() allocated this instance (in...
Definition: fossil-db.h:376
A container for storing generic error state.
Definition: fossil-util.h:692
FSL_EXPORT int fsl_stmt_cached_yield(fsl_stmt *st)
"Yields" a statement which was prepared with fsl_db_prepare_cached(), such that that routine can once...
fsl_db_role_t
This enum defines type ID tags with which the API tags fsl_db instances so that the library can figur...
Definition: fossil-core.h:83
FSL_EXPORT int fsl_db_get_bufferv(fsl_db *db, fsl_buffer *tgt, char asBlob, char const *sql, va_list args)
va_list counterpart of fsl_db_get_buffer().
Db handle wrapper class.
Definition: fossil-db.h:105
#define FSL_EXPORT
Definition: fossil-config.h:19
FSL_EXPORT int fsl_stmt_each_f_dump(fsl_stmt *stmt, void *state)
A fsl_stmt_each_f() impl, intended primarily for debugging, which simply outputs row data in tabular ...
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()...
fsl_commit_hook_f hook
Definition: fossil-db.h:44
int doRollback
Internal flag for communicating rollback state through the call stack.
Definition: fossil-db.h:172
FSL_EXPORT fsl_id_t fsl_db_g_id(fsl_db *db, fsl_id_t defaultValue, char const *sql,...)
Convenience form of fsl_db_get_id() which returns the value directly but provides no way of checking ...
FSL_EXPORT int fsl_db_preparev(fsl_db *db, fsl_stmt *tgt, char const *sql, va_list args)
va_list counterpart of fsl_db_prepare().
Generic list container type.
Definition: fossil-util.h:150
FSL_EXPORT int fsl_stmt_each(fsl_stmt *stmt, fsl_stmt_each_f callback, void *callbackState)
Calls the given callback one time for each result row in the given statement, iterating over stmt usi...
FSL_EXPORT int fsl_db_get_double(fsl_db *db, fsl_double_t *rv, char const *sql,...)
The double counterpart of fsl_db_get_int32().
int role
Describes what role(s) this db connection plays in fossil (if any).
Definition: fossil-db.h:119
FSL_EXPORT int fsl_db_close(fsl_db *db)
Closes the given db handle and frees any resources owned by db.
FSL_EXPORT int fsl_db_get_blobv(fsl_db *db, void **rv, fsl_size_t *stmtLen, char const *sql, va_list args)
va_list counterpart of fsl_db_get_blob().
Represents a prepared statement handle.
Definition: fossil-db.h:321
FSL_EXPORT fsl_stmt * fsl_stmt_malloc()
Allocates a new, cleanly-initialized fsl_stmt instance using fsl_malloc().
fsl_dbh_t * dbh
Underlying db driver handle.
Definition: fossil-db.h:124
FSL_EXPORT int fsl_db_exec(fsl_db *db, char const *sql,...)
Executes a single SQL statement, skipping over any results it may have.
FSL_EXPORT fsl_id_t fsl_stmt_g_id(fsl_stmt *stmt, int index)
Convenience form of fsl_stmt_get_id() which returns the value directly but cannot report errors...
int(* fsl_stmt_each_f)(fsl_stmt *stmt, void *state)
A callback interface for use with fsl_stmt_each() and fsl_db_each().
Definition: fossil-db.h:682
FSL_EXPORT fsl_int64_t fsl_db_g_int64(fsl_db *db, fsl_int64_t defaultValue, char const *sql,...)
Convenience form of fsl_db_get_int64() which returns the value directly but provides no way of checki...
FSL_EXPORT int fsl_db_init(fsl_error *err, char const *zFilename, char const *zSchema,...)
Initializes the given database file.
FSL_EXPORT int fsl_stmt_bind_id(fsl_stmt *stmt, int index, fsl_id_t v)
Binds v to the given 1-based parameter index.
FSL_EXPORT int fsl_stmt_bind_text(fsl_stmt *stmt, int index, char const *v, fsl_int_t n, char makeCopy)
Binds the first n bytes of v as text to the given 1-based bound parameter column in the given stateme...
FSL_EXPORT int fsl_stmt_col_count(fsl_stmt const *stmt)
Returns the result column count for the given statement, or -1 if !stmt or it has not been prepared...
FSL_EXPORT const fsl_stmt fsl_stmt_empty
Empty-initialized fsl_stmt instance, intended for copy-constructing.
Definition: fossil-db.h:398
FSL_EXPORT int fsl_stmt_get_int32(fsl_stmt *stmt, int index, fsl_int32_t *v)
Gets an integer value from the given 0-based result set column, assigns *v to that value...
sqlite3 fsl_dbh_t
A level of indirection to "hide" the actual db driver implementation from the public API...
Definition: fossil-db.h:86
FSL_EXPORT char * fsl_db_random_hex(fsl_db *db, fsl_size_t n)
Returns n bytes of random lower-case hexidecimal characters using the given db as its data source...
FSL_EXPORT int fsl_db_each(fsl_db *db, fsl_stmt_each_f callback, void *callbackState, char const *sql,...)
Expects sql to be a SELECT-style query which (potentially) returns a result set.
FSL_EXPORT char const * fsl_db_filename(fsl_db const *db, fsl_size_t *len)
If db is not NULL then this function returns its name (the one used to open it).
FSL_EXPORT char * fsl_db_g_text(fsl_db *db, fsl_size_t *len, char const *sql,...)
Convenience form of fsl_db_get_text() which returns the value directly but provides no way of checkin...
FSL_EXPORT int fsl_stmt_get_int64(fsl_stmt *stmt, int index, fsl_int64_t *v)
Gets an integer value from the given 0-based result set column, assigns *v to that value...
FSL_EXPORT fsl_size_t fsl_db_stmt_cache_clear(fsl_db *db)
Immediately cleans up all cached statements.
FSL_EXPORT int fsl_db_attach(fsl_db *db, const char *zDbName, const char *zLabel)
ATTACHes the file zDbName to db using the databbase name zLabel.
FSL_EXPORT int fsl_stmt_bind_null(fsl_stmt *stmt, int index)
Binds NULL to the given 1-based parameter index.
FSL_EXPORT int fsl_db_before_commit(fsl_db *db, char const *sql,...)
A special-purposes utility which schedules SQL to be executed the next time fsl_db_transaction_end() ...
FSL_EXPORT int fsl_stmt_bind_blob(fsl_stmt *stmt, int index, void const *v, fsl_size_t len, char makeCopy)
Binds the first n bytes of v as a blob to the given 1-based bound parameter column in the given state...
FSL_EXPORT fsl_db * fsl_db_malloc()
Allocates a new fsl_db instance().
FSL_EXPORT int fsl_db_get_doublev(fsl_db *db, fsl_double_t *rv, char const *sql, va_list args)
va_list counterpart of fsl_db_get_double().
FSL_EXPORT int fsl_db_get_int32(fsl_db *db, fsl_int32_t *rv, char const *sql,...)
Runs a fetch-style SQL query against DB and returns the first column of the first result row via *rv...
FSL_EXPORT const char * fsl_db_role_label(enum fsl_db_role_t r)
Returns a db name string for the given fsl_db_role value.
fsl_int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
FSL_EXPORT int fsl_stmt_bind_int64(fsl_stmt *stmt, int index, fsl_int64_t v)
Binds v to the given 1-based parameter index.
FSL_EXPORT const fsl_db fsl_db_empty
Empty-initialized fsl_db structure, intended for copy initialization.
Definition: fossil-db.h:242
FSL_EXPORT int fsl_db_eachv(fsl_db *db, fsl_stmt_each_f callback, void *callbackState, char const *sql, va_list args)
va_list counterpart to fsl_db_each().
FSL_EXPORT void fsl_db_err_reset(fsl_db *db)
Resets any error state in db, but might keep the string memory allocated for later use...
void * state
Definition: fossil-db.h:46
FSL_EXPORT fsl_int32_t fsl_stmt_g_int32(fsl_stmt *stmt, int index)
Convenience form of fsl_stmt_get_int32() which returns the value directly but cannot report errors...
FSL_EXPORT char * fsl_db_unix_to_iso8601(fsl_db *db, fsl_time_t j, char localTime)
Returns the given Julian date value formatted as an ISO8601 string (with a fractional seconds part if...
FSL_EXPORT int fsl_stmt_bind_int32_name(fsl_stmt *stmt, char const *param, fsl_int32_t v)
Equivalent to fsl_stmt_bind_int32() but binds to a named parameter.
FSL_EXPORT int fsl_db_transaction_rollback(fsl_db *db)
Equivalent to fsl_db_transaction_end(db, 1).
FSL_EXPORT int fsl_db_exec_multiv(fsl_db *db, const char *sql, va_list args)
va_list counterpart of db_exec_multi().
int colCount
Number of result columns in this statement.
Definition: fossil-db.h:344
A general-purpose buffer class, analog to Fossil v1's Blob class, but it is not called fsl_blob to av...
Definition: fossil-util.h:632
FSL_EXPORT char fsl_db_exists(fsl_db *db, char const *sql,...)
Runs the given SQL query on the given db and returns non-0 (true) if the query returns any rows...
long long int fsl_int64_t
Definition: fossil-config.h:94
FSL_EXPORT int fsl_db_before_commitv(fsl_db *db, char const *sql, va_list args)
va_list counterpart to fsl_db_before_commit().
FSL_EXPORT int fsl_db_transaction_begin(fsl_db *db)
Begins a transaction on the given db.
FSL_EXPORT int fsl_stmt_bind_double(fsl_stmt *stmt, int index, fsl_double_t v)
Binds v to the given 1-based parameter index.
void const * allocStamp
A marker which tells fsl_db_close() whether or not fsl_db_malloc() allocated this instance (in which ...
Definition: fossil-db.h:216
FSL_EXPORT int fsl_db_rollback_force(fsl_db *db)
Forces a rollback of any pending transaction in db, regardless of the internal transaction begin/end ...
fsl_cx * f
Fossil Context on whose behalf this instance is operating, if any.
Definition: fossil-db.h:111
FSL_EXPORT int fsl_db_get_id(fsl_db *db, fsl_id_t *rv, char const *sql,...)
The fsl_id_t counterpart of fsl_db_get_int32().
FSL_EXPORT int fsl_stmt_bind_int64_name(fsl_stmt *stmt, char const *param, fsl_int64_t v)
Equivalent to fsl_stmt_bind_int64() but binds to a named parameter.
FSL_EXPORT int fsl_db_transaction_commit(fsl_db *db)
Equivalent to fsl_db_transaction_end(db, 0).
int paramCount
Number of bound parameter indexes in this statement.
Definition: fossil-db.h:351
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_db_get_buffer(fsl_db *db, fsl_buffer *tgt, char asBlob, char const *sql,...)
Similar to fsl_db_get_text() and fsl_db_get_blob(), but writes its result to tgt, overwriting (not ap...
char * filename
Holds the file name used when opening this db.
Definition: fossil-db.h:140
FSL_EXPORT int fsl_stmt_bind_blob_name(fsl_stmt *stmt, char const *param, void const *v, fsl_int_t len, char makeCopy)
Equivalent to fsl_stmt_bind_blob() but binds to a named parameter.
FSL_EXPORT int fsl_stmt_bind_double_name(fsl_stmt *stmt, char const *param, fsl_double_t v)
Equivalent to fsl_stmt_bind_double() but binds to a named parameter.
FSL_EXPORT int fsl_db_get_sizev(fsl_db *db, fsl_size_t *rv, char const *sql, va_list args)
va_list counterpart of fsl_db_get_size().
fsl_int64_t fsl_int_t
fsl_int_t is a signed integer type used to denote "relative" ranges and lengths, or to tell a routine...
FSL_EXPORT int fsl_db_get_int32v(fsl_db *db, fsl_int32_t *rv, char const *sql, va_list args)
va_list counterpart of fsl_db_get_int32().
FSL_EXPORT int fsl_stmt_param_count(fsl_stmt const *stmt)
Returns the bound parameter count for the given statement, or -1 if !stmt or it has not been prepared...
int beginCount
Counter for fsl_db_transaction_begin/end().
Definition: fossil-db.h:158
FSL_EXPORT char * fsl_db_julian_to_iso8601(fsl_db *db, fsl_double_t j, char msPrecision, char localTime)
Returns the given Julian date value formatted as an ISO8601 string (with a fractional seconds part if...
FSL_EXPORT int fsl_db_preparev_cached(fsl_db *db, fsl_stmt **st, char const *sql, va_list args)
The va_list counterpart of fsl_db_prepare_cached().
double fsl_double_t
fsl_double_t is the double type used by the library.
int(* fsl_commit_hook_f)(void *state)
Potential TODO.
Definition: fossil-db.h:41
int priorChanges
Internal change counter.
Definition: fossil-db.h:181
FSL_EXPORT fsl_double_t fsl_db_julian_now(fsl_db *db)
Returns the current time in Julian Date format.
FSL_EXPORT int fsl_stmt_bind_null_name(fsl_stmt *stmt, char const *param)
Equivalent to fsl_stmt_bind_null_name() but binds to a named parameter.
fsl_list beforeCommit
List of SQL commands (char *) which should be executed prior to a commit.
Definition: fossil-db.h:199
FSL_EXPORT int fsl_db_select_slist(fsl_db *db, fsl_list *tgt, char const *fmt,...)
Expects fmt to be a SELECT-style query.
FSL_EXPORT char const * fsl_stmt_sql(fsl_stmt *stmt, fsl_size_t *len)
Returns the SQL string used to prepare the given statement, or NULL if !stmt or stmt has not been pre...
FSL_EXPORT int fsl_db_get_size(fsl_db *db, fsl_size_t *rv, char const *sql,...)
The fsl_size_t counterpart of fsl_db_get_int32().
FSL_EXPORT int fsl_db_get_int64v(fsl_db *db, fsl_int64_t *rv, char const *sql, va_list args)
va_list counterpart of fsl_db_get_int64().
int flags
Internal state flags.
Definition: fossil-db.h:362
FSL_EXPORT int fsl_db_transaction_end(fsl_db *db, char doRollback)
Decrements the transaction counter incremented by fsl_db_transaction_begin() and commits or rolls bac...
FSL_EXPORT int fsl_db_err_get(fsl_db const *db, char const **msg, fsl_size_t *len)
If db is not NULL this behaves like fsl_error_get(), using the db's underlying error state...
FSL_EXPORT int fsl_stmt_reset(fsl_stmt *stmt)
Equivalent to fsl_stmt_reset2(stmt, 0).
FSL_EXPORT char const * fsl_db_name(fsl_db const *db)
If a db name has been associated with db then it is returned, otherwise NULL is returned.
FSL_EXPORT void fsl_db_sqltrace_enable(fsl_db *db, FILE *outStream)
If db is an opened db handle, this registers a debugging function with the db which traces all SQL to...
FSL_EXPORT fsl_int64_t fsl_stmt_g_int64(fsl_stmt *stmt, int index)
Convenience form of fsl_stmt_get_int64() which returns the value directly but cannot report errors...
fsl_buffer sql
SQL used to prepare this statement.
Definition: fossil-db.h:337
fsl_error error
Holds error state from the underlying driver.
Definition: fossil-db.h:133
fsl_db * db
The db which prepared this statement.
Definition: fossil-db.h:325
FSL_EXPORT char const * fsl_stmt_g_text(fsl_stmt *stmt, int index, fsl_size_t *outLen)
Convenience form of fsl_stmt_get_text() which returns the value directly but cannot report errors...
FSL_EXPORT int fsl_db_detach(fsl_db *db, const char *zLabel)
The converse of fsl_db_detach().
FSL_EXPORT void * fsl_db_g_blob(fsl_db *db, fsl_size_t *len, char const *sql,...)
Convenience form of fsl_db_get_blob() which returns the value directly but provides no way of checkin...
FSL_EXPORT int fsl_stmt_get_text(fsl_stmt *stmt, int index, char const **out, fsl_size_t *outLen)
Gets a string value from the given 0-based result set column, assigns *out (if out is not NULL) to th...
fsl_size_t rowCount
The number of times this statement has fetched a row via fsl_stmt_step().
Definition: fossil-db.h:357
FSL_EXPORT int fsl_stmt_step(fsl_stmt *stmt)
"Steps" the given SQL cursor one time and returns one of the following: FSL_RC_STEP_ROW, FSL_RC_STEP_DONE, FSL_RC_STEP_ERROR.
FSL_EXPORT fsl_double_t fsl_db_string_to_julian(fsl_db *db, char const *str)
Uses the given db to convert the given time string to Julian Day format.
FSL_EXPORT fsl_size_t fsl_db_g_size(fsl_db *db, fsl_size_t defaultValue, char const *sql,...)
Convenience form of fsl_db_get_size() which returns the value directly but provides no way of checkin...
fsl_stmt * cacheHead
An internal cache of "static" queries - those which do not rely on call-time state unless that state ...
Definition: fossil-db.h:208
FSL_EXPORT int fsl_db_open(fsl_db *db, char const *dbFile, int openFlags)
Opens the given db file and populates db with its handle.
FSL_EXPORT int fsl_db_get_blob(fsl_db *db, void **rv, fsl_size_t *len, char const *sql,...)
The Blob counterpart of fsl_db_get_text().
FSL_EXPORT int fsl_stmt_get_blob(fsl_stmt *stmt, int index, void const **out, fsl_size_t *outLen)
The Blob counterpart of fsl_stmt_get_text().
FSL_EXPORT char fsl_db_existsv(fsl_db *db, char const *sql, va_list args)
va_list counterpart of fsl_db_exists().
FSL_EXPORT fsl_double_t fsl_db_g_double(fsl_db *db, fsl_double_t defaultValue, char const *sql,...)
Convenience form of fsl_db_get_double() which returns the value directly but provides no way of check...
FSL_EXPORT fsl_double_t fsl_stmt_g_double(fsl_stmt *stmt, int index)
Convenience form of fsl_stmt_get_double() which returns the value directly but cannot report errors...
FSL_EXPORT int fsl_db_get_textv(fsl_db *db, char **rv, fsl_size_t *rvLen, char const *sql, va_list args)
va_list counterpart of fsl_db_get_text().
FSL_EXPORT char fsl_db_table_has_column(fsl_db *db, char const *zTableName, char const *zColName)
Returns non-0 (true) if the database (which must be open) table identified by zTableName has a column...
FSL_EXPORT int fsl_stmt_reset2(fsl_stmt *stmt, char resetRowCounter)
Resets the given statement, analog to sqlite3_reset().
FSL_EXPORT int fsl_db_before_commit_hook(fsl_db *db, fsl_commit_hook_f f, int sequence, void *state)
Potential TODO.
FSL_EXPORT int fsl_stmt_bind_int32(fsl_stmt *stmt, int index, fsl_int32_t v)
Binds v to the given 1-based parameter index.
char * name
Holds the database name for use in creating queries.
Definition: fossil-db.h:147
int openStatementCount
Debugging/test counter.
Definition: fossil-db.h:153
FSL_EXPORT int fsl_db_select_slistv(fsl_db *db, fsl_list *tgt, char const *fmt, va_list args)
The va_list counterpart of fsl_db_select_slist().
FSL_EXPORT int fsl_db_get_int64(fsl_db *db, fsl_int64_t *rv, char const *sql,...)
The int64 counterpart of fsl_db_get_int32().
Potential TODO.
Definition: fossil-db.h:43
FSL_EXPORT fsl_id_t fsl_db_last_insert_id(fsl_db *db)
Returns the row ID of the most recent insertion, or -1 if !db, db is not connected, or 0 if no inserts have been performed.