JDB/Implementation

From J Wiki
Jump to: navigation, search
JDB: Layout Columns | Queries Σ | API: Structural Records | Client/Server | Implementation | Examples


Meta Data

Database

A database has two files in addition to the tables:

  • dir has the Tables and Columns definitions
  • trans has the next database transaction number

Table

A table has three files in addition to the columns:

  • d0 is the active record mask, i.e. 1=active, 0=deleted.
  • d1 has deleted records as a 2-column matrix: transaction number, autoid
  • d2 has three integers:
    • number of fixed-length rows allocated in mapped files
    • next autoid number
    • transaction number of last change to table

Note that d1, autoid and tranid suffice to build an active record mask for any transaction number, so an earlier snapshot of the data can be read. If a task other than the server is reading the database directly, it should read the database transaction number at outset, and then build its own active record masks. File d0 is not strictly necessary, but serves to reduce the overhead of opening a table.

When a database is opened, each table is checked for any transactions that failed to complete, and rolled back if needed.

Transactions

Only record updates are wrapped in transactions. Structural changes such as add/delete tables and columns are assumed done when the database is offline, and are not wrapped in transactions.

Once a record is written, it is not changed, except possibly by a maintenance program that rebuilds the database.

Insert is done by append to end of file.

Delete is done by updating d0 and d1.

Updates are done by delete plus insert. An update preserves the record autoid.

Use verb Alter to include several changes in a single transaction.

A transaction is completed when the database transaction number is incremented.

Error Handling

Errors are handled by verb throw, defined as 13!:8&101.

Within JDB, the code that updates the database is wrapped in try/catch, with the catch handler reverting changes as appropriate, and calling throw when done.