module Sqlite:API to work with Sqlite databasessig
..end
exception Sqlite_error of string
db_rc
for functions that take a db
as the first
argument, and with vm_rc
for functions that take a vm
as the first
argument.
When the error code is RC_misuse
, it usually means that a programming
error was made. An attempt to use an invalidated db
handle (i.e. after
Sqlite.close
was called on this handle) is an example.
exception Sqlite_done
exception Sqlite_busy
exception Sqlite_null_value
Sqlite.step_simple
when a null value is found in the
result row.type
db
type
vm
compile
or compile_simple
function.
Column names and data types are stored in a vm
handle as soon as
they become known.
A vm
handle also stores the status code of the last operation
which took the virtual machine handle as a parameter. For example,
Sqlite.compile
stores its status code in the db
handle because
it takes the db
handle as the first parameter, but Sqlite.finalize
stores its status code in the vm
handle passed.
type
rc =
| |
RC_ok |
| |
RC_error |
| |
RC_internal |
| |
RC_perm |
| |
RC_abort |
| |
RC_busy |
| |
RC_locked |
| |
RC_nomem |
| |
RC_readonly |
| |
RC_interrupt |
| |
RC_ioerr |
| |
RC_corrupt |
| |
RC_notfound |
| |
RC_full |
| |
RC_cantopen |
| |
RC_protocol |
| |
RC_empty |
| |
RC_schema |
| |
RC_toobig |
| |
RC_constraint |
| |
RC_mismatch |
| |
RC_misuse |
| |
RC_nofls |
| |
RC_auth |
| |
RC_format |
db
handle or a vm
handle depending on the function called.
Note: RC_misuse is the common error code when an invalid db
or vm
is passed to a function.val db_open : string -> db
Sqlite.db_open f_name
opens the database file f_name
and
returns a database handle.val db_close : db -> unit
Sqlite.db_close db_handle
closes the database file associated with
db_handle
and invalidates the handle. Raises an Sqlite_error
exception
if an invalid handle is passed.val exec : db -> string -> unit
Sqlite.exec db_handle q_string
executes the query q_string
. The
query result is ignored.val last_insert_rowid : db -> int
Sqlite.last_insert_rowid db_handle
returns the rowid of the last
inserted row.val db_rc : db -> rc
Sqlite.db_rc db_handle
returns the status code of the last
operation on db_handle
.vm
handle
after the first attempt. When there are no result rows left (or there
were no rows to fetch at all), an attempt to fetch a row raises an
Sqlite_done
exception and immediately finalizes the virtual machine
involved. Column names and types can be obtained even after the vm
handle is finalized (and thus invalidated) if it was created with a
compile
call with the third parameter set to true
.val compile : db -> string -> int -> bool -> vm * int * bool
Sqlite.compile db_handle q_string skip keep_col_info
reads
a single query from the string q_string
, skipping skip
initial
characters, and compiles it. It returns a vm
handle, the position
in q_string
of the still-unused part of the string, and a boolean
value telling if the end of the string has been reached.
Passing character positions is necessary for strings containing
more than one statement, since a vm
is associated with a single
statement.
If keep_col_info
is true, the vm
handle will retain information
about column names and data types after it is finalized (e.g. with
sqlite.finalize
), but not yet garbage-collected. Of course, the
information is saved only if it is known at the time of finalization.
val compile_simple : db -> string -> vm
Sqlite.compile_simple db_handle q_string
compiles a single query,
read from the beginning of the string q_string
. It returns a vm
handle.
Any unused remainder of the q_string
is ignored. Information about
column names and types is not available after the vm
is finalized.val step : vm -> string -> string array
Sqlite.step vm default_value
executes vm
to return the next
row of the result as a string array. Null values are replaced with
default_value
. Even if the query compiled to vm
is not expected
to return any rows, the function should be called at least once for
the query to be executed. The use of exec
is preferred for such
queries, however.val step_simple : vm -> string array
Sqlite.step_simple
is the same as Sqlite.step
, except that it
raises a Sqlite_null_value
exception if the result row contains a
null value, instead of replacing it with a default value.val step_opt : vm -> string option array
Sqlite.step_opt vm
executes vm
and returns the next row
of the result as a string option array. Null values are returned as
None
array elements, and non-null values as Some(value)
elements.val finalize : vm -> unit
Sqlite.finalize vm
finalizes vm explicitly, thus invalidating the
handle. The vm is finalized automatically when an error occurs or when
fetching is attempted on a query all of whose rows have been fetched.
Sqlite.finalize
may be used to terminate query execution at will,
whenever needed.val vm_rc : vm -> rc
Sqlite.vm_rc vm
returns the status code of the last operation on vm.val column_names : vm -> string array
Sqlite.column_names vm
returns the column names of the query result.
If Sqlite.compile
was called with a true third parameter, the column
names are available even after vm is finalized.val column_types : vm -> string array
Sqlite.column_types vm
returns the column types of query result.
If Sqlite.compile
was called with a true third parameter, the column
types are available even after vm is finalized.