SCRYDOSBox-XReferenceSessionstatusAlso in MAME
status
Ask whether a session is open and what the machine is doing, without moving it.
status()
Try it
Is the emulator still up, and where is it stopped?
status(){
"summary": "status: alive, stopped",
"status": "ok",
"pending": {"arm": [], "disarm": 0, "symbols_load": false, "base_remeasure": false},
"cpu_mode": "real",
"pc": "F000:0000FFF0",
"declarations": {"breakpoints": 0, "watches": 0, "regpoints": 0}
}The machine is stopped in real mode at F000:0000FFF0, the reset vector. pending is empty, so nothing waits for the next stop, and declarations counts no saved breakpoint or watch.
The whole reply
{
"summary": "status: alive, stopped",
"status": "ok",
"pid": "<volatile>",
"conf": "./demos/bricks/bricks.conf",
"conf_digest": "af0834584e2dad05",
"watched": true,
"bound_s": 900,
"elapsed_s": "<volatile>",
"captures": "off",
"state_dir": "./tmp/demos/tour/files/states",
"last_stop": {
"stop_seq": 1,
"pc": "F000:0000FFF0",
"cause": "no declared code breakpoint at F000:0000FFF0, and the debugger does not say which row stopped the machine, so what made this stop cannot be told",
"since_s": "<volatile>",
"wall_at": "<volatile>"
},
"pending": {"arm": [], "disarm": 0, "symbols_load": false, "base_remeasure": false},
"cpu_mode": "real",
"pc": "F000:0000FFF0",
"declarations": {"breakpoints": 0, "watches": 0, "regpoints": 0},
"presence": true
}Arguments
Takes no argument.
What comes back
- last_stop
- Where the machine last stopped: its
pcandcause, andsince_s, how long ago. Unavailable, with why, when there is no stop to report. - pc
- Where the machine stands now (
SSSS:OOOOOOOO), read from the registers: aset_registermovingCS:IPshows here, not inlast_stop. While running, unavailable;last_stop.pcanswers. - cpu_mode
real,protected,pagedorVM86, read at a stop. Unavailable while the program runs.- stopped_on_its_own
- Present when the machine had stopped and no call had reported it yet.
statusrecords that stop as the last one. - pending
- What waits for the next stop:
arm, the breakpoints declared while the program ran; adisarmcount; and whether asymbols_loador abase_remeasureis queued. - symbols_held
- Present while a
startsymbol table waits for its program: itspath, itsbase_fromandwaiting_for, the program's file name.
All 18 reply fields
bound_s(number)bundle(string)captures(string)conf(string)conf_changed_on_disk(boolean or object)image_changed_on_disk(boolean or object)conf_digest(string)cpu_mode(string or object)declarations(object)elapsed_s(number)pc(string or object)pending(object)pid(integer)presence(boolean or object)state_dir(string)symbols_held(object)output_bytes_dropped(integer)watched(boolean)
Why it works this way
status answers in every state: with no session, while the machine runs and once the session is broken. It is where you learn why another tool does not answer.
At a stop it also sets the breakpoints that were declared while the program ran, and says so in applied_on_stop.
session carries five warnings, each only while it is true: program, range_widened, conf_changed_on_disk, image_changed_on_disk and output_bytes_dropped.
More on why
-
conf_changed_on_disk: the conf file changed sincestart. It isfalsetoo when the file is gone. -
image_changed_on_disk: the executable the loaded symbol table was checked against was written since, as a rebuild under an open session does. -
output_bytes_dropped: the emulator printed more than the server keeps. -
program: the program that ran inside DOS is gone. It isstate: exitedwithnameandseen_by, orstate: faultwithfault, the message DJGPP writes as a program dies. -
programis read at the stops that answer a call, never while the program runs, so a session that never stops never learns it. -
presenceistruewhen the border is drawn,falsewhen it was asked off, or the reason it is not drawn. -
declarationscounts the server's own savedbreakpoints,watchesandregpoints(stops on a register condition). -
last_stopalso carriesstop_seqandwall_at. -
pid,conf,conf_digest,watched,bound_s,elapsed_s,captures,state_dirandbundledescribe the process, asstartset it up.
Related tools
The contract your client receives
What the session is right now. It records a stop no tool has reported
(`stopped_on_its_own`) and applies what was queued while the guest ran
(`applied_on_stop`).
Reply: `last_stop` (`stop_seq`, `pc`, `cause`, `since_s`, `wall_at`) and `pending` (`arm`
refs, a `disarm` count, `symbols_load`, `base_remeasure`), both unavailable or empty once a
session has ended; with a session also `presence`, `pid`,
`conf`, `conf_digest`, `conf_changed_on_disk`, `image_changed_on_disk`, `watched`, `bound_s`,
`elapsed_s`, `output_bytes_dropped`, `captures`, `state_dir`, `declarations`, `pc` and
`cpu_mode`;
`symbols_held` (`path`, `base_from`, `waiting_for`) while a `start` table waits for its
program, which costs a memory-chain read at every stop. `session` carries `alive`,
`running`, `altered` and each alarm while it holds.
Reference: REFERENCE.md, What every reply carries.