SCRYDOSBox-XReferenceBreakpointsdeclaration_clearAlso in MAME

DOSBox-XBreakpoints

declaration_clear

Remove saved breakpoints, registerpoints or watches: one by its ref, or every one of a kind.

declaration_clear(kind, ref="", all=false)

Try it

On Bricks, the game this repository builds, stopped with the watch on the score that the watch_add entry sets.
Ask

Remove the watch on the score.

Call
declaration_clear(kind="watch", ref="score")
Reply 4 of 4 fields
{
  "summary": "declaration_clear watch score: 1 cleared",
  "status": "ok",
  "declarations_cleared": 1,
  "disarmed": ["BPMEM 08DF:0615 (3C)", "BPMEM 08DF:0616 (00)"]
}

The watch on score is gone, and disarmed lists the two debugger rows it used, one per byte.

The whole reply
JSON
{
  "summary": "declaration_clear watch score: 1 cleared",
  "status": "ok",
  "declarations_cleared": 1,
  "disarmed": ["BPMEM 08DF:0615 (3C)", "BPMEM 08DF:0616 (00)"]
}

Arguments

kind one of "breakpoint", "regpoint", "watch", required
breakpoint, regpoint or watch: what to clear. breakpoint covers interrupt breakpoints too.
ref string, default ""
The one to clear, as the reply that saved it gave its ref. Left empty with all=True.
all boolean, default false
true clears every one of kind, and takes no ref.

What comes back

declarations_cleared
How many were removed from the saved breakpoints file.
disarmed
The debugger rows removed, as the debugger listed them, checked by reading its list back.
pending_disarm
Debugger rows still to remove: at the next stop while the program runs, or on the next call when a removal failed.
All 3 reply fields
  • declarations_cleared (integer)
  • disarmed (array)
  • pending_disarm (array)

What it refuses

Why it works this way

It removes only what this server set: a foreign row, one typed through debug, is never deleted.

The saved breakpoint or watch is removed at once. While the program runs the debugger cannot be asked, so its rows go at the next stop: pending_disarm lists them, and that stop's reply confirms it in applied_on_stop.

A SEG:OFF and a registerpoint's condition match in any spelling. A symbol or an interrupt breakpoint's BPINT text must be the exact text the saving reply carried.

The contract your client receives
Text
Clear the declarations of `kind`: all with `all=True`, or the one named by the exact `ref`
its declaring reply carried; `breakpoint` takes `breakpoint_interrupt` rows too. Removes only
what this store armed, the declarations at once and, on a running guest, their debugger
rows at the next stop (`pending_disarm`); a `foreign` entry is never deleted.

Refused: a `ref` matching none, naming the refs held; neither `ref` nor `all`, or both
(`bad_argument`).

Reply: `declarations_cleared`, `disarmed`, `pending_disarm` (removed at the next stop),
`note`.

Reference: REFERENCE.md, Breakpoints and watches.
Tools