SCRYDOSBox-XReferenceMachinelogAlso in MAME

DOSBox-XMachine

log

Read the newest log lines that match a pattern: the program's, the emulator's, both, or the DOS calls the program made.

log(pattern, channel, limit=40, labels=false, since_mark=0)

Try it

On Bricks, the game this repository builds, started with logfile, after a ball was served and lost.
Ask

What did the game log about serves, hits and lost balls?

Call
log(pattern="SERVE|HIT|LOST", channel="guest")
Reply 2 of 7 fields
{
  "summary": "log guest /SERVE|HIT|LOST/: 6 of 6 lines",
  "lines": [
    "Bochs port E9h: HIT 0 7",
    "Bochs port E9h: HIT 5 6",
    "Bochs port E9h: HIT 5 0",
    "Bochs port E9h: SERVE",
    "Bochs port E9h: HIT 5 9",
    "Bochs port E9h: LOST"
  ]
}

Six lines of the game's own log match, oldest first. Each opens with Bochs port E9h:, the emulator's mark on a line the program wrote to port 0xE9.

The whole reply
JSON
{
  "summary": "log guest /SERVE|HIT|LOST/: 6 of 6 lines",
  "status": "ok",
  "pattern": "SERVE|HIT|LOST",
  "channel": "guest",
  "lines_total": 6,
  "truncated": false,
  "lines": ["Bochs port E9h: HIT 0 7", "Bochs port E9h: HIT 5 6", "Bochs port E9h: HIT 5 0", "Bochs port E9h: SERVE", "Bochs port E9h: HIT 5 9", "Bochs port E9h: LOST"]
}

Arguments

pattern string, required
A regular expression each line is searched for. It is never empty: . matches every line.
channel one of "guest", "emulator", "all", "dos", required
Which log to read. guest is the program's port 0xE9 lines, emulator DOSBox-X's own, all both with each line tagged, dos the program's INT 21h calls.
limit integer (>= 1, <= 400), default 40
How many of the newest matching lines to return: 1 to 400. Left out, 40.
labels boolean, default false
true adds labels: the lines returned, counted by their first word. Left out, no count.
since_mark integer (>= 0), default 0
A byte position in the log: only lines written after it are read. Left out or 0, the whole log is read.

What comes back

lines
The newest limit matching lines, oldest first. Not on dos.
lines_total
How many lines matched in all, not how many came back.
truncated
true when more matched than came back.
labels
With labels=true, the returned lines counted by their first word: a quick view of who is writing.
calls
On dos, the matching calls in place of lines, each with the registers DOS took, the ones it handed back and its result.
calls_dropped
On dos, how many of the oldest calls the server no longer holds.
All 8 reply fields
  • calls (array)
  • calls_dropped (integer)
  • channel (string)
  • labels (object)
  • lines (array)
  • lines_total (integer)
  • pattern (string)
  • truncated (boolean)

What it refuses

Why it works this way

guest, emulator and all are three views of one file, so one since_mark position serves all three. all is the file in order, each line tagged [guest] or [emulator] .

dos is another record: every INT 21h call the program made, with its result, on a session started with dos_calls. There pattern is matched against each call's line and lines_total counts calls.

An empty lines is an answer: nothing matched. A log with no line from the program at all is refused, so that silence is never read as no match. While the program runs a line it has only now written may not be in the file yet, and note says so.

More on why
  • On dos, each call is two rows of the debugger's DOSTRACE, one as DOS takes it and one as DOS hands it back, paired by number.
  • On dos, each call of calls holds in and out, the registers DOS took and handed back; out.cf is the carry flag.
  • error is the code and its name, for the calls that report failure by the carry: AH 38h and up. An older call answers in AL and gets none.
  • returned is false for a call DOS has not handed back yet, as at a stop inside it.
  • switched: true marks a call that never returned to its caller, as an EXEC or an exit: the registers are then another program's, so no result is claimed.
  • The emulator's own int21 and fileio lines, switched on in the conf's [log] section, are written before DOS runs the call, so they never carry its result.
  • time_s and returned_s are seconds of emulated time since power-on, the clock run_for reports.
The contract your client receives
Text
The session's log, one `channel` (`guest`, `emulator`, `all`, `dos`) filtered by the
Python regex `pattern`; `limit` keeps the newest matches; `labels=True` adds `labels`, the
matching lines counted by first word.
`since_mark` (a byte position, from a `mark`) reads only what follows. Needs a session with
`logfile`. `dos`, the guest's INT 21h calls and no other interrupt, instead needs a session
started with `dos_calls`, matches `pattern` against each call's `line` (`#20 08BC:0139 psp
0x08BC 0x3D open MISSING.TXT -> error 2 file not found`), counts calls where the others count
lines (the matches among the calls the server holds), and takes no `since_mark` or `labels`;
past those, `calls_dropped` says how many of the oldest went. Works on a running guest.

Reply: `channel`, `lines` (not on `dos`), `lines_total`, `truncated`, `labels`, `pattern`,
`note`; on the DOS channel `calls` instead of `lines` (each `n`, `time_s`, `cpu_mode`,
`caller`, `psp`, `function`, `name`, `file`, `in`, `out`, `error`, `returned`, `returned_s`,
`switched`, `line`), and `calls_dropped` (on `dos`, past the calls held). INVALID with `code`:
no `logfile`, no log yet, no guest instrumentation, `limit` out of range, an empty or bad
pattern, an unknown channel (`process` is refused by name), a `since_mark` naming no
position. To wait for a line use `log_wait`.

Reference: REFERENCE.md, The log.
Tools