Skip to content

Commit 0851d24

Browse files
cinderblockclaude
andcommitted
README: scope down .prj encoding, point at ACE OLE DB for real edits
The current `ewe` mdb encode path is text-only same-length byte patching. That covers the vendor/price/MPN editing workflow and is where this thread stops in this repo. Reimplementing Access's storage engine (page splits, B-tree maintenance, free-space tracking) is a multi-month effort orthogonal to the project's interop mission, so the README now says so explicitly. For anyone who needs general-purpose `.prj` edits (numeric/date columns, length-changing text, ambiguous values), the recommended path is to drive Microsoft's own Access engine via the ACE OLE DB driver or the Access ODBC driver from a separate Windows-only tool — likely using `node-odbc` as an N-API binding. The diff logic already in `src/encodeMdb.ts` is reusable for generating `UPDATE` statements. No code change; documentation and scope only. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent f2ca58b commit 0851d24

1 file changed

Lines changed: 41 additions & 19 deletions

File tree

README.md

Lines changed: 41 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -55,28 +55,50 @@ Dates become ISO 8601 strings; binary blob fields (`ole` columns) become
5555
`{ "_bytes": "base64", "value": "..." }` envelopes so the data survives a
5656
JSON round-trip.
5757

58-
**Encode is in-place-edit only.** Writing a valid Jet 3 file from
59-
scratch would mean reimplementing Access's page/B-tree storage engine,
60-
which is out of scope. Instead `ewe` patches an existing `.prj`:
58+
**Encode is a deliberately narrow byte-patch path, not a real Jet writer.**
59+
Reimplementing Access's storage engine (page splits, B-tree index
60+
maintenance, free-space tracking, `MSysObjects` invariants) is out of
61+
scope for this project — `ewd`/`ewe` exist to move data **out** of
62+
Electronics Workbench, not to clone Microsoft's database engine.
63+
64+
What `ewe` does on an `mdb` input today:
6165

6266
1. You decode with `ewd` to produce `<file>.prj.json`.
6367
2. You edit the JSON in your text editor (or with a script).
64-
3. You run `ewe edited.json` and `ewe` diffs the edited JSON against
65-
the original `.prj`, then byte-patches each changed cell.
66-
67-
Today's limits (each enforced by the encoder, with a clear "skipped"
68-
report when violated):
69-
70-
- Only `text` and `memo` columns. Numeric / date / OLE edits are skipped.
71-
- New value must have the same byte length as the old value. Length
72-
changes would require row reflow / free-space accounting (planned).
73-
- Old value must appear exactly once in the file. If it's ambiguous
74-
(collides with another row) or missing, the change is skipped.
75-
76-
These constraints cover the typical vendor / price / MPN editing
77-
workflow because those values are usually unique and you usually
78-
substitute one same-length identifier for another. The skipped list
79-
tells you exactly when they don't.
68+
3. You run `ewe edited.json`. It diffs the edited JSON against the
69+
original `.prj`, then for each changed cell where:
70+
- the column is `text` or `memo`,
71+
- the new value has the **same byte length** as the old,
72+
- the old value appears **exactly once** in the file,
73+
74+
it overwrites the bytes in place. Anything that violates those
75+
constraints is skipped, and `--verbose` prints the reason per cell.
76+
77+
This is enough for the typical vendor / price / MPN editing workflow
78+
because those values are usually unique and you usually substitute one
79+
same-length identifier for another. It is **not** a general-purpose
80+
editor and we don't intend to grow it into one.
81+
82+
### If you want general-purpose `.prj` edit support
83+
84+
Not planned in this repo. The clean way to add it is a separate,
85+
optional, Windows-only tool that drives Microsoft's own Access engine:
86+
87+
- **ACE OLE DB Provider** (`Microsoft.ACE.OLEDB.12.0` / `16.0`) — free
88+
Redistributable from Microsoft, reads & writes both `.mdb` and `.accdb`.
89+
- **Access ODBC driver** — same engine, ODBC interface. Pair with
90+
[`node-odbc`](https://github.com/markdirish/node-odbc) (N-API native
91+
addon) and issue plain SQL: `UPDATE SYS_USER_DATA SET USER_DEFINED_7 =
92+
? WHERE Component_ID = ?`. The diff logic we already have for
93+
edited-JSON → changed-cells would generate those statements directly.
94+
- **Jet OLE DB 4.0** — older, **32-bit only**, still works for Jet 3
95+
`.mdb` files like NI's `.prj`.
96+
97+
That path requires Windows + a driver install and so deliberately lives
98+
outside this cross-platform repo's CI. The current byte-patch encode
99+
covers the vendor/price editing case; for anything harder, route through
100+
Access (or the ACE driver, or DAO/ADO) instead of expecting `ewe` to
101+
grow into a full Jet writer.
80102

81103
## Format detection
82104

0 commit comments

Comments
 (0)