SQLITE-m2/docs/summary-v0.2.0.md

m2SQLITE summary — v0.2.0 (2026-09-24)

SQLite bindings for GNU Modula-2 (gm2 16.0.1, SQLite 3.46.1 system libsqlite3.so.0, Linux; API reference sqlite-master/ 3.54.0). All builds verified with make; tests 5/5 green, showcase exits 0.

v0.1.0 — core binding + showcase

• src/SQLite.def — thin FOR "C" core API (~60 procedures): version/sourceid/threadsafe, open/open_v2/close/close_v2, exec, errcode/errmsg/errstr/error-offset/free, complete, busy-timeout, autocommit, changes/rowid, extended codes, limit, prepare_v2/prepare_v3, step/finalize/reset/clear-bindings, data/column-count, sql/expanded-sql, stmt-readonly/busy, all bind_*, all column_*, parameter count/name/index; result-code, open-flag, column-type, prepare-flag and limit-id constants
• lib/SQLiteUtils.def/.mod — CStrToM2, ErrMsg/ErrStr/ LibVersionStr, StaticDestr/TransientDestr (STATIC/TRANSIENT sentinels), BindTextCopy/BindBlobCopy, ExecSimple/ExecWithErr
• tests/ — version, open (+open_v2), exec (incl. change counters and error capture), prepare/bind/column round trip + run_tests.sh
• examples/ — version, hello_db (bind-insert, select-print)
• showcases/showcase_all — calls every SQLite procedure and every SQLiteUtils helper in 7 sections; verifies values, prints results
• Makefile — gm2 build (-c helper to .o, then link) for tests, examples and showcases; pkg-config with runtime-lib fallback; optional local-sqlite amalgamation target
• .gitignore — ignores sqlite-master/, build/, artefacts, *.db
• README.md — status table, layout, build/test, usage, FFI notes

v0.2.0 — custom SQL functions

• src/SQLite.def — function API (+30 procedures): XFunc/XStep/ XFinal/XDestroy callback types (ContextHandle, ValueHandle), create_function/create_function_v2, all value_* readers (blob/double/int/int64/text/bytes/type/numeric-type), all result_* writers (blob/blob64/double/error(+code/toobig/nomem)/int/int64/null/ text/text64/value/zeroblob/zeroblob64), context helpers (aggregate_context, user_data, context_db_handle, get/set_auxdata); UTF-encoding and function-flag constants (UTF8/UTF16 variants, DETERMINISTIC/DIRECTONLY/SUBTYPE/INNOCUOUS/ RESULT_SUBTYPE/SELFORDER1). 16-bit and window-function APIs deliberately omitted (noted in README roadmap).
• lib/SQLiteUtils — ValueText (value handle into CHAR array), ResultTextCopy (TRANSIENT text result)
• tests/test_func — 17 registered functions: scalar double/text/ int64/blob-echo/type-probe/null-passthrough, sized results (zeroblob/64, blob64, text64), error paths (exact codes 1/18/7 verified), msum aggregate with aggregate_context state, user_data call counting and context_db_handle check, auxdata set/get round trip, create_function_v2 + DETERMINISTIC flag
• showcases/showcase_all — new section [8]: m2tax scalar and m2total aggregate over a table (close moves to [9])
• Key result: module-level Modula-2 procedures ARE C-compatible function pointers (proven by spike against real libsqlite3, then by the suite); NIL accepted for unused callbacks

GM2 FFI rules learned (encoded in code)

1. DEFINITION MODULE FOR "C" needs EXPORT UNQUALIFIED, otherwise the linker looks for Module_proc instead of the C symbol.
2. No *) and no (* inside (* *) comments (nested-comment open and early close) — C pointer spellings need spaces (char * never char *), destructor never void (*)).
3. INTEGER <-> int, LONGINT <-> sqlite3_int64, REAL <-> double (libc.atof/strtod return REAL); opaque handles = ADDRESS.
4. ARRAY OF CHAR params = char * (pass literals, -1 for lengths); mandatory ** OUT params = VAR, optional ones (errmsg, pzTail) = plain ADDRESS taking ADR(var) or NIL.
5. SQLITE_TRANSIENT/STATIC are macros, pass VAL(ADDRESS, -1/0) (wrapped by TransientDestr/StaticDestr).
6. INTEGER constants garble through C varargs (printf("%d")) — route them via variables first.
7. No dev package needed: link /usr/lib/x86_64-linux-gnu/libsqlite3.so.0 directly when pkg-config sqlite3 is absent.
8. Callback types (PROCEDURE (ADDRESS, ...)) cross into C as plain function pointers; NIL fills unused slots. Index C pointer arrays with a VAL overlay onto POINTER TO ARRAY OF ADDRESS.
9. This SQLite build rejects the AS t(v) column-alias form in FROM (VALUES ...); use bare column1 names in tests.

Next

Window functions (create_window_function) + collations, incremental BLOB I/O + backup API, extended result-code constants.