Manual · The book

Two people, one record — how it is handled automatically, and by hand from a script.

Single-user: nothing to think about

On a single-user application a lock is granted the instant it is asked for — there is nobody to contend with. Everything below is invisible and free there; it matters the moment a project is built with Neuridion PRO as a Client/Server pair.

Automatic — the whole model, and you write no code for it

Locking is pessimistic and never waits: a record is granted at once or refused at once, and a refusal names who holds it.

• The first change takes the lock. Reading never locks — a list, a report, a card that only shows a record hold nothing. The moment a person changes a field of an existing record, its lock is taken on the server. A brand-new record needs none: it exists for nobody else yet.
• A refusal is shown, not swallowed. If someone else holds it, the field turns red, the character just typed goes back to the record's truth, the cursor moves to the field, and a bubble says “Being edited by Anna.” — the name, not a rule.
• Saving, discarding or closing releases it. A lock lives seconds — from the first change to the save — not “as long as I keep the window open”. The instant the change is saved every blocked window is told, and the red mark clears itself.
• A lunch break cannot wedge anything. A connection gone silent loses its locks after thirty seconds; a clean disconnect frees them at once.
• The revision counter is the net beneath the lock. Every effective save raises the record's revision; a save landing on a stale revision is refused with a sentence rather than overwriting somebody's work — so even a script that never touched a lock cannot quietly clobber a change.

You do not switch this on. Build the pair with PRO and it is simply how editing behaves; a single-user build acts as if every lock is always yours.

By hand — from a script

Sometimes a script, not a form, is the one changing a record — or one action has to hold a record across several writes. Three methods on a record do it, speaking to the same server ledger the forms use:

• record.lock() — take the lock. Returns true if it is yours (or already was), false if someone else holds it. On a single-user application it is always true.
• record.unlock() — let a held lock go. Harmless if you held none.
• record.lockedBy() — the name of whoever holds it right now, or null if it is free.

// A "Book" button on the invoice form: hold the record
// while we change it — but only if nobody else is editing it.
const invoice = form.record;
if (invoice.lock()) {
    invoice.status = "booked";
    invoice.save();          // saving releases the lock by itself
} else {
    messages.alert("Being edited by " + invoice.lockedBy()
                   + " — try again in a moment.");
}

You rarely need this — the automatic form lock covers ordinary editing. Reach for it when a script changes records without a form, or when one action must hold a record for several writes in a row. A saved record's lock is already gone, so an explicit unlock() is only for the case where you locked but then decided not to save.