===============================================================================

SQLite3 Object
Original Publication by James J Keene PhD
Updated for use with SQLite3.dll (version 3) by Alexander Hofer

History:
V1.0 | May 14,2005 | Creation
V1.1 | Apr 22,2006 | ADD: UTF8 en-/decoding
V1.2 | Nov 08,2006 | UPD: Declare SQLite-Functions as CDECL
     |             | DEL: Stack clean up (not needed with CDECL)
V1.3 | Aug 17,2007 | UPD: New call to sqlite3_prepare_v2()

===============================================================================

The SQLite3 object is a database tool using an "embeddable SQL database engine"
by D. Richard Hipp and requires sqlite3.dll (SQLite version 3).
Many thanks to Mr. Hipp for sqlite3.dll and its documentation.

The HotBasic SQLite3 object requires sqlite3.dll in the program directory
or in the usual .dll paths.

In general, (1) .Open a database, (2) .Execute/.Query makes a request and
(3) .Close the database for use by other programs.

After (1), .Handle returns the SQLite3 database handle.

After (2), .ColumnNames, .Error, .Row, .RowValue, and .ColumnCount provide
information on .Query results.  After .Query results are examined,
.Finalize should be invoked to complete the cycle of a single command.

===============================================================================

Close
  Closes previously opened database
  Returns 0 (SQLITE3_OK) if there is no error, otherwise an error code
  LONG = MySQLite3.Close

ColumnCount
  Returns number of columns in query result
  LONG = MySQLite3.ColumnCount

ColumnNames
  Returns names of columns in query result
  STRING = MySQLite3.ColumnNames

Error
  Returns description of error
  STRING = MySQLite3.Error

Execute(command AS STRING)
  Executes one or more SQL statements
  Use this function only for SQL statements which doesn't return any results
  (E.g. CREATE, INSERT, UPDATE, DELETE, DROP...)
  Returns 0 (SQLITE3_OK) if there is no error, otherwise an error code
  LONG = MySQLite3.Execute("SQL statement")

FieldSeparator(separator AS STRING)
  Defines one character which will be used as field separator
  Default = "|"
  MySQLite3.Fieldseparator = "#"

Finalize
  Completes .Query cycle
  Returns 0 (SQLITE3_OK) if there is no error, otherwise an error code
  LONG = MySQLite3.Finalize

Handle
  Returns handle of an open SQL database, otherwise 0
  LONG = MySQLite3.Handle

LibVersion
  Returns SQLite library version
  STRING = MySQLite3.LibVersion

Open(filename AS STRING)
  Open the SQLite3 database file "filename"
  If the database file does not exist, then a new database will be created
  Returns 0 (SQLITE3_OK) if there is no error, otherwise an error code
  LONG = MySQLite3.Open("Filename")

Query(command AS STRING)
  Executes one SQL SELECT statement
  Use this function only for SQL SELECT statements which returns results
  Returns 0 (SQLITE3_OK) if there is no error, otherwise an error code
  LONG = MySQLite3.Query("SQL SELECT statement")

Row
  Retrieves one row of data in .RowValue
  Returns 100 (SQLITE3_ROW) if the SQL statement returns any data
    Call MySQLite3.Row again
  Returns 101 (SQLITE3_DONE) if SQL statement has finished executing
    Call MySQLite3.Finalize to complete MySQLite3.Query cycle
  LONG = MySQLite3.Row

RowValue
  Returns one row of query result
  STRING = MySQLite3.RowValue

===============================================================================

SQLite3 return codes:

  SQLITE_OK           0  Successful result
  SQLITE_ERROR        1  SQL error or missing database
	SQLITE_INTERNAL     2  An internal logic error in SQLite
	SQLITE_PERM         3  Access permission denied
	SQLITE_ABORT        4  Callback routine requested an abort
	SQLITE_BUSY         5  The database file is locked
	SQLITE_LOCKED       6  A table in the database is locked
	SQLITE_NOMEM        7  A malloc() failed
	SQLITE_READONLY     8  Attempt to write a readonly database
	SQLITE_INTERRUPT    9  Operation terminated by sqlite_interrupt()
	SQLITE_IOERR       10  Some kind of disk I/O error occurred
	SQLITE_CORRUPT     11  The database disk image is malformed
	SQLITE_NOTFOUND    12  (Internal Only) Table or record not found
	SQLITE_FULL        13  Insertion failed because database is full
	SQLITE_CANTOPEN    14  Unable to open the database file
	SQLITE_PROTOCOL    15  Database lock protocol error
	SQLITE_EMPTY       16  (Internal Only) Database table is empty
	SQLITE_SCHEMA      17  The database schema changed
	SQLITE_TOOBIG      18  Too much data for one row of a table
	SQLITE_CONSTRAINT  19  Abort due to contraint violation
	SQLITE_MISMATCH    20  Data type mismatch
	SQLITE_MISUSE      21  Library used incorrectly
	SQLITE_NOLFS       22  Uses OS features not supported on host
	SQLITE_AUTH        23  Authorization denied
	SQLITE_ROW        100  sqlite_step() has another row ready
	SQLITE_DONE       101  sqlite_step() has finished executing

===============================================================================
