SQLITE-m2

m2SQLITE — SQLite bindings for GNU Modula-2

Thin DEFINITION MODULE FOR "C" bindings of SQLite for gm2 (GCC 16 / GNU Modula-2), covering the core C API: open/close, exec, prepare/step/finalize, bind, column access and error reporting.

Reference sources: sqlite-master/ (SQLite 3.54.0, fossil checkout). That folder is git-ignored (see .gitignore); the binding only needs the SQLite shared library at link time.

Status

Starter set, verified with gm2 16.0.1 + SQLite 3.46.1 (system libsqlite3.so.0) on Linux:

Module	C header	Contents
SQLite	<sqlite3.h> (sqlite-master/src/sqlite.h.in)	version, open/close, exec, errcode/errmsg, prepare/step/finalize/reset, bind*, column, changes/rowid, busy_timeout, limits, custom functions (createfunction, value, result_*, aggregate/userdata/auxdata context), incremental BLOB I/O, online backup, all 82 extended result codes, get_table/free_table
SQLiteUtils (lib/)	—	CStrToM2() + ErrMsg()/ErrStr()/LibVersionStr(), StaticDestr()/TransientDestr(), BindTextCopy()/BindBlobCopy(), ValueText()/ResultTextCopy(), BackupToFile(), GetTable()/TableCell()/FreeTable(), ExecSimple()/ExecWithErr()

Window functions (create_window_function), collations and sessions come next.

Layout

m2SQLITE/
  src/            FOR "C" .def binding (SQLite)
  lib/            pure-M2 helpers (SQLiteUtils)
  tests/          gm2 smoke tests + run_tests.sh
  examples/       version, hello_db
  showcases/      showcase_all (exercises the whole binding)
  build/          generated binaries (git-ignored)
  sqlite-master/  upstream SQLite sources (git-ignored)

Prerequisites

• gm2 (tested: 16.0.1 experimental)
• SQLite runtime (/usr/lib/x86_64-linux-gnu/libsqlite3.so.0, tested: 3.46.1). The dev package (pkg-config sqlite3) is used when present but is not required.

Build & test

make            # tests + examples + showcases -> build/
./tests/run_tests.sh
./build/examples/version
./build/examples/hello_db
./build/showcases/showcase_all

make check is make tests + the runner script.

Optional: build a local amalgamation from the reference tree (takes a few minutes, needs tclsh + cc):

make local-sqlite   # -> build/sqlite/sqlite3.o

Usage

FROM SQLite IMPORT DbHandle, SQLiteOk,
   sqlite3_open, sqlite3_close;
FROM SQLiteUtils IMPORT ExecSimple, ErrMsg;

Compile your program with the binding search path and the C library:

gm2 -Isrc -Ilib myprog.mod lib/SQLiteUtils.mod -o myprog -lsqlite3
# without the dev package, link the runtime lib directly:
gm2 -Isrc -Ilib myprog.mod lib/SQLiteUtils.mod -o myprog \
  /usr/lib/x86_64-linux-gnu/libsqlite3.so.0

Notes:

• Opaque sqlite3 * / sqlite3_stmt * travel as ADDRESS (DbHandle / StmtHandle, NIL == NULL).
• ARRAY OF CHAR parameters map onto char *: string literals and CHAR arrays can be passed directly (see gm2 "Interface to C" node). Pass -1 for nByte/n on NUL-terminated text.
• VAR handle parameters map onto T **: sqlite3_open(":memory:", db), sqlite3_prepare_v2(db, sql, -1, stmt, NIL).
• Optional char ** OUT params (errmsg, pzTail) are plain ADDRESS: pass ADR(msg) or NIL.
• bind_text/bind_blob destructors: pass VAL(ADDRESS, -1) for SQLITE_TRANSIENT (copy) or use BindTextCopy()/BindBlobCopy().
• Custom functions: declare module-level procedures of the XFunc / XStep / XFinal types and pass them to sqlite3_create_function (C calls them directly — verified); NIL for unused callbacks. Index the argv vector with a VAL overlay onto an ADDRESS array (see tests/test_func.mod ArgAt).
• INTEGER <-> int, LONGINT <-> sqlite3_int64, REAL <-> double (see gm2 "Elementary data types" node and libc.atof). Pass INTEGER constants through a variable before handing them to C varargs (printf("%d") garbles literal constants).

Showcase

showcases/showcase_all calls every SQLite procedure and every SQLiteUtils helper in seven sections (info, settings, errors, prepare, binds, columns, close) and prints each result.

Roadmap

1. Window functions (create_window_function) + collations.
2. Sessions/changesets (ext/session).