SCRYMAMEReferenceBreakpointsdeclaration_clearAlso in DOSBox-X
declaration_clear
Remove saved breakpoints, registerpoints or watches: one by its ref, or every one of a kind.
declaration_clear(kind, ref="", cpu="", all=false, space="program")
Try it
take_credit, and the control an earlier run_to left on wait_frame.Remove every breakpoint.
declaration_clear(kind="breakpoint", all=true){
"summary": "declaration_clear breakpoint all: 2 cleared, 2 disarmed",
"status": "ok",
"declarations_cleared": 2,
"disarmed": ["1 @ A631 if (++temp0)==0", "3 @ D676"],
"while_running": false
}Both saved breakpoints are gone, and disarmed shows the two debugger rows removed. The first was the control: its condition counts in temp0 and never comes true.
The whole reply
{
"summary": "declaration_clear breakpoint all: 2 cleared, 2 disarmed",
"status": "ok",
"declarations_cleared": 2,
"disarmed": ["1 @ A631 if (++temp0)==0", "3 @ D676"],
"while_running": false
}Arguments
- kind one of
"breakpoint","regpoint","watch", required breakpoint,regpointorwatch: what to clear.- ref string, default
"" - The one to clear, as the reply that saved it gave its
ref. Left empty withall=True. - cpu string, default
"" - Clear on this cpu only. Left empty, on every cpu.
- all boolean, default
false trueclears every one ofkind, and takes noref.- space one of
"program","io", default"program" iowhenrefis a port watch. Onlywatchtakes it.
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.
- tallies_removed
- The
countandcapturewatches whose removal was sent to MAME, each withtally_id,removal,lines_aheadandcall. - while_running
truewhen the machine was running as the call arrived. The clear works either way.
All 4 reply fields
declarations_cleared(integer)disarmed(array)tallies_removed(array)while_running(boolean)
What it refuses
- An empty
refwithoutall, or both together (bad_argument). - A
refthat matches nothing: the message names the refs saved (unknown_ref). spaceon a kind other thanwatch, or together withall(bad_argument).
Why it works this way
It removes only what this server set: a foreign row, one typed through debug, is never deleted.
A ref is read once, so a clear reaches only its own kind, and a name is never taken for the address its letters spell. An address matches in any spelling; a symbol must be the one saved.
With no cpu it reaches that ref on every cpu. In a file several sessions use, all=True also clears rows another session saved, which read inherited: true: clear by ref when they are not yours.
More on why
- Removing a
countor acaptureis sent to MAME's console and applied when it next reads a line. - It is never sent twice: the id is the range, and a second send could remove a watch declared since.
- A removal MAME did not carry out shows on every reply under
session.tallies_not_removed. - If the debugger still lists a row after its removal,
notesays so and names thedebugcommand that removes it. all=Trueonwatchremoves the port watches too.- A registerpoint's condition or an
exprwatch matches as typed but for its numbers, read as the console reads them:7fff,0x7fff,$7fffand#32767are one. - There a run of letters such as
abstays a name and keeps its case. A saved address written in bare hex is that address. - With a
state_dir,all=Truereaches only the rows saved in that folder. Without one, it reaches every session's rows of the same system and symbol file. - Declaring the range again installs over a count not removed, keeping its totals, and a clear then removes it. Its
tallies_not_removedrow stays: this session counted past a removal.
Related tools
The contract your client receives
Clear the declarations of `kind` that `ref` names (as its declaring reply gave it), or
every one with `all=True` and no `ref`, on `cpu` or every cpu. Disarms what this server
armed; a foreign row is never deleted. `space="io"` clears a watch's io tap. Works on a
running machine.
Refused: an empty `ref` without `all`; a `ref` matching none (`unknown_ref`, naming the
refs held); `space` for a kind other than `watch`.
Reply: `declarations_cleared`, `disarmed`, `while_running`, `tallies_removed` (removing an io
tap), `note`.
Reference: REFERENCE.md, Breakpoints and watches.