# -----------------------------------------------------------------------------
#  DF3VT - a SQLite Virtual Table interface to DF3 data files.
# -----------------------------------------------------------------------------

df3vt is part of the df3 tools project.

it provides a loadable extension module for the SQLite3 database which
implements virtual tables exposing given DF3 data files, as defined in
the manual of the Persistence Of Vision Raytracer 3.7.x software.

building requires a 64-bit GNU/Linux os(*), the usual GCC tool chain,
and the 'df3' external library.  execute:

  $ make

since the extension is for personal use, no installation target is
provided; simply copy the 'df3vt.so' file to a suitable location and
amend your '~/.sqliterc' file if necessary.

usage example, using the sqlite3 shell:

  sqlite> .header on
  sqlite> .load df3vt
  sqlite> CREATE VIRTUAL TABLE df3 USING
     ...> df3vt(file='spiral.df3', readonly='yes');
  sqlite> SELECT * FROM df3 WHERE z = 2;
  x	y	z	v
  0	0	2	0
  1	0	2	0
  <<<<<<snip>>>>>>> 
  sqlite>

this version (0.1.0) is my first go at writing a SQLite virtual
table module.  tables are read only, UPDATEs are simply ignored
for now, and "ORDER BY" clause handling (indexing), too, is not
yet implemented.

if, on loading, sqlite3 displays an "error during initialization",
the cause (likely) is a library version mismatch; df3vt requires
version 3.8.7 or later.

if the argument to 'readonly' is an unreasonably long string
(1023+ chars), an internal fixed-size  buffer will overflow.

see the comments at the top of the source file for the details.

(*) the extension should compile cleanly on Windows too, however,
since df3vt, like all df3 tools, expects file names to be POSIX.1
compliant, you cannot use a drive letter, backslashes, spaces, etc.

enjoy, jr.

