Skip to content

stdkv.md

Latest commit

 

History

History
70 lines (57 loc) · 3.03 KB

stdkv.md

File metadata and controls

70 lines (57 loc) · 3.03 KB
module STDKV
tag v0.9.0
phase M3 — VSL/MSL S1 storage seam
stable stable
since v0.9.0
synopsis minimal keyed record-store seam (the S1 storage contract)
labels
exists
get
kill
set
errors
conformance
see_also
STDFS

STDKV — minimal keyed record-store seam

STDKV is the portable storage seam (S1 of the MSL⟷VSL coordination plan): a tiny record store that addresses a value by (collection, key, field). It is the engine-neutral half of the storage seam that the VistA VSLFS adapter binds to FileMan's Database Server (DBS) API (GETS^DIQ / $$GET1^DIQ / UPDATE^DIE / FILE^DIE / FIND1^DIC) above the m/v waterline — mapping collection → file, key → IENS, field → field number.

On a bare engine STDKV is its own reference back end (a process-private global), so the seam is real and testable with no VistA present. The VSLFS adapter swaps that back end for FileMan while keeping the four-verb signature identical, so callers are unchanged across back ends.

This is a record store, not a filesystem — STDFS stays path/byte I/O. The contract is deliberately minimal: only the four verbs the storage acceptance needs, and the seam carries no parsing/formatting (that stays in the caller).

Public API

All four verbs are extrinsic functions — call them with $$, never do (a $$-style quit <value> label cannot be invoked with do). The side-effecting verbs ($$set/$$kill) return 1.

Call Purpose
$$set^STDKV(coll,key,field,value) store value at (coll,key,field) → 1
$$get^STDKV(coll,key,field,default) read the field value, or default when unset
$$exists^STDKV(coll,key) 1 iff the record (coll,key) has any field set
$$kill^STDKV(coll,key) remove a whole record (idempotent) → 1

Round-trip (the shape STDKVTST proves)

set ok=$$set^STDKV("demo.cfg",1,".01","hello")   ; store
write $$get^STDKV("demo.cfg",1,".01","none")     ; "hello"
write $$exists^STDKV("demo.cfg",1)               ; 1
set ok=$$kill^STDKV("demo.cfg",1)                ; remove
write $$exists^STDKV("demo.cfg",1)               ; 0
write $$get^STDKV("demo.cfg",1,".01","none")     ; "none" (default)

Engine support & portability

Fully portable — pure global I/O, no engine-specific arms. Records live in the process-private ^STDLIB($job,"kv",coll,key,field), so runs never bleed into one another and parallel suites are safe. Values are stored verbatim, so binary / control-byte values round-trip byte-exact under ydb_chset=M. Verified GREEN on both YottaDB (m-test-engine) and IRIS (foia-t12), 12/12 assertions.

The seam

The four verbs carry ; doc: @seam STDKV, so they project into the seams block of dist/stdlib-manifest.json (and dist/seam-snapshot.json) as the contract_version: 1 storage contract. v-stdlib's VSLFS pins this contract (via dist/msl-seam-pin.json) and binds it to FileMan DBS; a signature change here without a contract_version bump is a red gate (the seam bump-forcer).