SCRYDOSBox-XReferenceSessionstatusAlso in MAME

DOSBox-XSession

status

Ask whether a session is open and what the machine is doing, without moving it.

status()

Try it

On Bricks, right after that start: the machine is stopped at its first instruction.
Ask

Is the emulator still up, and where is it stopped?

Call
status()
Reply 6 of 16 fields
{
  "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
JSON
{
  "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 pc and cause, and since_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: a set_register moving CS:IP shows here, not in last_stop. While running, unavailable; last_stop.pc answers.
cpu_mode
real, protected, paged or VM86, 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. status records that stop as the last one.
pending
What waits for the next stop: arm, the breakpoints declared while the program ran; a disarm count; and whether a symbols_load or a base_remeasure is queued.
symbols_held
Present while a start symbol table waits for its program: its path, its base_from and waiting_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 since start. It is false too 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 is state: exited with name and seen_by, or state: fault with fault, the message DJGPP writes as a program dies.

  • program is read at the stops that answer a call, never while the program runs, so a session that never stops never learns it.

  • presence is true when the border is drawn, false when it was asked off, or the reason it is not drawn.

  • declarations counts the server's own saved breakpoints, watches and regpoints (stops on a register condition).

  • last_stop also carries stop_seq and wall_at.

  • pid, conf, conf_digest, watched, bound_s, elapsed_s, captures, state_dir and bundle describe the process, as start set it up.

The contract your client receives
Text
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.
Tools