SCRYDOSBox-XReferenceSessionstartAlso in MAME

DOSBox-XSession

start

Start DOSBox-X from your conf file and leave the machine stopped at the debugger, at its first instruction.

start(conf="", cwd="", session_seconds=null, shared=false, display=null, fullscreen=null, size=null, flags=null, break_on_int3=false, program="", logfile="", capture_video=false, captures_dir="", plan=null, settle_seconds=null, input_port=0, state_dir="", binary="", background=null, presence=true, dos_calls=false, log_categories=null, guest_files=null, symbols="", base_from="program", profile="")

Try it

On Bricks, the game this repository builds. The example session starts it for a person to watch, with a log file for what the game writes.
Ask

Start Bricks in a window I can watch without losing my keyboard, for at most fifteen minutes, and keep its log.

Call
start(shared=true, background=true, display="<host>", conf="./demos/bricks/bricks.conf",
    cwd="./demos/bricks", session_seconds=900, logfile="./tmp/demos/tour/files/e9.log",
    state_dir="./tmp/demos/tour/files/states", captures_dir="./tmp/demos/tour/files/captures")
Reply 6 of 25 fields
{
  "status": "ok",
  "conf": "./demos/bricks/bricks.conf",
  "watched": true,
  "bound_s": 900,
  "logfile": "./tmp/demos/tour/files/e9.log",
  "kept": "1 saved for `promote`"
}

The session may live 900 seconds (bound_s), and watched says it has a window. kept says the arguments were saved as a start profile, for promote to write into a repository.

The whole reply
JSON
{
  "summary": "<volatile>",
  "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",
  "shared": true,
  "ready_after_s": "<volatile>",
  "argv": "<volatile>",
  "binary": "<volatile>",
  "binary_origin": "<volatile>",
  "version": "<volatile>",
  "debugger_commands": ["A20", "BPIF", "CAPTURE", "DOSTRACE", "LOADSTATE", "MEMDUMPLIN", "... 8 more"],
  "stub": "./src/scry_dosbox_x/guest/SCRY.COM",
  "input_port": "<volatile>",
  "background": true,
  "presence": true,
  "window": "<volatile>",
  "logfile": "./tmp/demos/tour/files/e9.log",
  "declarations": {
    "rearm": {"rearmed": [], "stale": [], "unresolved": [], "ambiguous": [], "unarmable": []}
  },
  "kept": "1 saved for `promote`"
}

Arguments

conf string, default ""
The DOSBox-X conf file to run, as it is. Required unless a start profile gives it.
cwd string, default ""
The folder the conf's relative paths resolve in. Required unless a start profile gives it.
session_seconds integer (>= 1, <= 14400), optional
The session's lifetime in seconds, after which the emulator is ended. Required unless a start profile gives it.
shared boolean, default false
true when a person watches: the session opens a window. Left out, it has none.
display integer, optional
Which display the window opens on, by the operating system's index. Needs shared=true; left out, 0, the main display.
fullscreen boolean, optional
true makes the window fill the display; DOSBox-X then captures the mouse, so its pointer no longer follows yours. Needs shared=true.
size string, optional
The window's size as WIDTHxHEIGHT, in the host's unit. Needs shared=true; left out, the conf's own size, else the largest 4:3 window the display holds.
flags array of string, optional
More command-line tokens for DOSBox-X, one list item each: ["-set", "cpu core=normal"]. They come after the server's own, so a -set of the same key wins.
break_on_int3 boolean, default false
true also stops at the program's own int 3, where a program marks a break. The stop at the debugger's first prompt still comes first.
program string, default ""
A program to run inside DOS once the conf's [autoexec] has finished. Left empty, none.
logfile string, default ""
A file that receives what the program writes to port 0xE9, its own debug log, which log and log_wait read. A file already there is overwritten.
capture_video boolean, default false
true records the run of program as video. It needs program.
captures_dir string, default ""
Where the emulator writes a capture it takes itself. Left empty, capture under the working directory.
plan array of object, optional
A list of calls to run right after the start, each {"op": <tool>, ...arguments}, run as perform runs a list.
settle_seconds number (>= 0, <= 600.0), optional
How long each wait of the plan may take, in seconds. Left out, 30.
input_port integer (>= 0, <= 65535), default 0
The TCP port the emulated COM1 dials, through which keys and mouse reach the program. Left at 0, a free one; any other is 1024 or above.
state_dir string, default ""
The folder state_write saves into, which stays after close. Left empty, the session's temporary folder, deleted at close.
binary string, default ""
The DOSBox-X to run: an executable, or on macOS a .app bundle holding one. Left empty, DOSBOX_X_BINARY, else the dosbox-x on the PATH.
background boolean, optional
true opens the window behind your other windows and leaves the keyboard focus where it is; false opens it in front. Left out, behind unless shared.
presence boolean, default true
Draws a border around the emulator's window while the session is open, brighter while a call runs the machine. false leaves it off.
dos_calls boolean, default false
true records every DOS call (INT 21h) the program makes, for log(channel="dos"). It needs a build whose debugger has DOSTRACE.
log_categories object, optional
DOSBox-X's own [log] categories, each with its level, written into logfile. It needs logfile.
guest_files array of string, optional
Up to 16 files on the host that the program is expected to leave. guest_file and close say what became of each.
symbols string, default ""
A symbol table, checked now and loaded at the first stop where DOS holds the program it is named after. symbols_load loads one later.
base_from one of "program", "cs", "ds", "es", "ss", "fs", "gs" (in any case), default "program"
Where the table's addresses start: program, the program's own load address, or a segment register read at a protected-mode stop. Left out, program.
profile string, default ""
A start profile: a saved set of start arguments, by its name under .scry/start/ or by a path. It fills only the arguments the call leaves out.

What comes back

window
With shared, where the window is. Its front is true when no other application's window covers its centre; it does not mean the window has the keyboard focus.
input_port
The TCP port the emulated COM1 dialled, or why no input connection was opened.
symbols
With symbols: held, the table's path; base_from; and checked, what comparing it with the executable beside it found.
profile
With a start profile: its name, its file, and supplied, the arguments it filled.
kept
Says that this start's arguments were saved as a start profile for promote, the tool that writes one into your repository's .scry/ folder.
start
With plan: the start's own fields sit here, beside the plan's account of its steps.
All 56 reply fields
  • activation (string)
  • asked_display (integer)
  • seen (object)
  • errors (array)
  • failed (object)
  • field (string)
  • got (any)
  • ran_path (string or object)
  • recorded (any)
  • replies_path (string or object)
  • steps_total (integer)
  • still_running (boolean)
  • stopped (object)
  • stops (object)
  • truncated (boolean)
  • verdict (string)
  • searched (array)
  • kept (string)
  • failed_at (integer or object)
  • held (integer)
  • ran (array)
  • steps_completed (integer)
  • argv (array)
  • background (boolean)
  • binary (string)
  • binary_origin (string)
  • 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)
  • debugger_commands (array)
  • declarations (object)
  • dos_calls (string)
  • elapsed_s (number)
  • guest_files (array)
  • input_port (integer or object)
  • log_categories (object)
  • logfile (string)
  • operations (array)
  • pid (integer)
  • presence (boolean or object)
  • ready_after_s (number)
  • rearm_refused (string)
  • shared (boolean)
  • start (object)
  • state_dir (string)
  • stub (string)
  • profile (object)
  • output_bytes_dropped (integer)
  • symbols (object)
  • version (string or object)
  • watched (boolean)
  • window (object)

What it refuses

Why it works this way

shared says whether a person watches. Without it the session has no window at all, and window cannot report one. With it the window opens on display, in front; add background=true to watch without losing the keyboard focus.

A start profile is a file of start arguments, .scry/start/<name>.json in a repository, so a session starts with start(profile="<name>"). The call's own arguments win and the profile fills the rest. The .scry/ folder is looked for upwards from the server's working directory, then from cwd.

The server runs the conf you name as it is and writes none of its own. It mounts its own folder on a drive letter the conf's [autoexec] leaves free and runs SCRY.COM from it, the helper that delivers keys and mouse inside DOS. So the conf must not exit before program runs.

More on why
you want arguments the window
Nobody watching shared=false, the default None. window refuses it as no_channel.
Somebody watching shared=true, with display and size or fullscreen if wanted On the display, in front, confirmed in the host's window list.
Watching and keeping the keyboard focus shared=true, background=true The same, opened behind your other windows.

The window's size.

A windowed session opens 40 px inside the display's corner. Its size is size when given, else the conf's windowresolution, else the largest 4:3 window the display's usable area holds. The menu bar, Dock and taskbar do not count as usable.

size is in the host's unit: points on macOS, real pixels on Windows. Every OpenGL output and Direct3D take a size, and so does an unset output on macOS and Windows; surface does not. Under an output that ignores it, size is refused, and without size the conf's size stays.

fullscreen under sdl output=surface is refused because that output fills the display by switching its video mode, and the window ends off screen. On macOS it is accepted on display 0 only: a start stopped at its first instruction reaches full screen on another display only once the program runs.

start waits until the host lists the window on that display. It does not check the size, since a stopped window keeps the conf's size until the program runs; window does. A watched window is not supported on Linux.

background only chooses where the window opens. How the focus stays with you is the host's: on macOS the emulator starts as a background application, and on Windows no program may take the foreground while start launches. A click or ALT moves the focus as always.

On Windows a start in front brings its window forward once it is up, and window.front says whether Windows allowed it.

The lifetime.

session_seconds is a hard limit because DOSBox-X's own time limit counts emulated time, which a machine stopped at the debugger never spends. A watchdog process, scry-dosbox-x-guardian in the process list, keeps the host's clock instead. It ends the emulator a few seconds past the limit, or soon after this server dies.

Flags.

  • A flag that sets what a named argument sets (-time-limit, sdl videodriver, log logfile, the conf, the program) is refused, naming the argument: coming after the server's, it would undo it.
  • So is a -set of sdl display, sdl fullscreen, sdl windowposition or sdl windowresolution, and -fullscreen.
  • A -set value with spaces is one token. A -set glued to its value is refused because DOSBox-X hangs on it.
  • A -set without = is refused because DOSBox-X ignores it with no error, and the setting would not apply.
  • key=value with no section is accepted, and a key the server owns is refused in that spelling too.
  • Without a window the server passes videodriver=dummy. It never passes -silent, which exits after AUTOEXEC.BAT and cannot keep a session open.

The program and its symbols.

  • program loads the input helper itself when the conf's autoexec does not run it. A copy of SCRY.COM in the conf that speaks another protocol is reported in the note.
  • A symbols table is compared with the executable beside it before anything starts. symbols.checked says how many global code symbols agreed, or why nothing could be compared.
  • It is compared again at the first stop that holds the program, since the executable can be rebuilt meanwhile. That stop's reply carries symbols_placed, once.
  • symbols_placed holds placed, path, load_segment in real mode, base and loaded; a refusal is placed: false with code and why.
  • base_from=program is the DOS load segment of a real-mode program. For a DJGPP COFF executable it is the selector CS holds at a protected-mode stop, where the code runs.
  • break_on_int3 has two limits that are the debugger's: an int 3 at the reset vector faults, and one at the address of a stop is stepped over by resume.
  • guest_files answers each file as path and before, what it was before the boot.

Speed.

[cpu] use dynamic core with fpu decides whether FPU code runs recompiled. Its auto takes FPU and MMX instructions off the dynamic core. A single-tasking DOS program that leans on the FPU then runs below real time with nothing in the session saying so, and a conf for it states true.

What else the reply says.

  • captures_dir and state_dir are created with their parents. state_dir in the reply is the folder in use.
  • shared, ready_after_s, argv, binary, binary_origin, version, background and presence say what the launch used.
  • A version the build would not give is available: false with a why, and never fails the start.
  • rearm_refused says why saved raw breakpoints could not be set again.
  • No free drive letter for the input helper is refused before anything starts.

Files, the emulator's log and the border.

  • A file a tool reads must be a regular file, never a folder. A tool never writes over a file unless its entry says it replaces one, as logfile does.
  • logfile is written under a name of lowercase words joined by hyphens, as every file the server writes, so a capital or a % in it is replaced.
  • At debug a log_categories category can write a line per event: files writes one per read once the [log] setting fileio is on. Turn on only what the question needs.
  • The border never changes another reply: a failure to draw it shows only in presence, in start and status.
  • While the debugger does not answer, the border is not redrawn. It catches up once a call is answered.
The contract your client receives
Text
Open one live DOSBox-X session from your conf, parked at the debugger.

Paths are absolute or `~`-led. `cwd`: where the conf's relative paths resolve. `binary`:
an executable or a `.app` carrying one, which `open` launches (macOS alone): that route
keeps `cwd` through DOSBox-X's own `working directory` setting, names the bundle in
`bundle`, and leaves the exit status to launchd, so `close` answers `unavailable` for it.
`session_seconds`: the lifetime.
`shared`: watched, in a window; false, headless.
`profile`: a repository's run recipe (`.scry/start/<name>.json`) or a path to one. Its keys
are this tool's arguments and fill only what the call does not give; the reply's `profile`
block names it and what it filled. The store is looked for from the server's directory, then
`cwd`.
`display`: the OS's display index for the window, 0 (the main display) when omitted;
`fullscreen`: the window fills it and DOSBox-X captures the mouse, so the guest pointer no
longer follows the host cursor; `size`: `WIDTHxHEIGHT` of the window in the host's unit,
else the largest 4:3 window the display's usable area holds. All three need `shared=true` and
are refused otherwise; `size` is also refused beside `fullscreen`, beyond the usable area
(naming it) and under an `sdl output` that ignores it; a `display` past the host's count is
refused naming the count. The server waits for the window to be listed on that display and
answers `window`; `window` judges the size once the guest runs.
`flags`: argv tokens, a `-set` value one token. `logfile`: the guest's E9 channel, for `log`,
`log_wait`, `drive`. `program` runs after autoexec; `capture_video` records it. `plan` runs
as `perform` does, a step `{"op": <tool>, ...arguments}`, each wait bounded by
`settle_seconds` (default 30). `input_port`: COM1's TCP port, 0 a free one.
`state_dir`: where `state_write` saves; empty, the session's scratch (gone at `close`).
`dos_calls`: record every INT 21h for `log(channel="dos")`, up to the build's row cap; the
server holds the newest 50000 calls it has read, `n` staying the file's number.
`log_categories`: `[log]` category to level, into `logfile`. `guest_files`: host files the
guest should leave, read by `guest_file` and `close`. `symbols`: a table `symbols_load`
reads, judged here and placed at the first stop where DOS holds the program its stem names
(`<stem>.exe`); `base_from` `program` (its own base) or a register, as `symbols_load`
measures one, at a protected-mode stop. That stop's reply says `symbols_placed` once
(`placed`, `path`, `load_segment` in real mode, `base`, `loaded`; refused: `placed:
false`, `code`, `why`); a later `symbols_load` replaces it.

Refused: a live session, a window that never appears on the asked display
(`window_not_visible`, the session left live to `window` or `close`), `flags` setting what
`display`, `fullscreen` or `size` own, `fullscreen` on `sdl output=surface` or, on macOS, on
a display other than 0, a bad path or `symbols` table,
`session_seconds` out of range, `capture_video` without `program`, an `input_port` other than
0 outside 1024-65535, `log_categories` without `logfile`, `dos_calls`
on a build with no `DOSTRACE`, `guest_files` naming a directory, one file twice or more than
16, or a session already live (`session_live`).

Reply: `pid`, `stub`, `window` (`display`, `bounds`, `onscreen`, `front`, `fullscreen`, with
`shared`; `front` says no other application's window covers its centre, not that it has the keyboard focus), `input_port`, `declarations` (`rearm`), `logfile`, `dos_calls`,
`log_categories`, `guest_files` (each when asked for: the log's path as written, the trace's
path, the categories set, each file as it was before the boot), `symbols` (`held`, `base_from`,
`checked`), and with a profile `profile` (`name`, `file`, `supplied`); with `plan`, these
facts sit under `start` beside the plan's account. `note` when the conf or `flags` select a
dynamic cpu core, which can pass over code breakpoints: start on
`flags=["-set", "cpu core=normal"]`.

Reference: REFERENCE.md, The session.

break_on_int3: Also stop at the guest's own `int 3`, where a program marks a break; the debugger's first prompt still comes first.

captures_dir: Where the emulator writes a capture it takes itself; empty, `capture` under the working directory.

background: Launch behind, keeping the caller's focus, or in front; omitted it is behind unless `shared`.

presence: Draw an edge around the emulator's window while this session is open: dim while idle, bright while a call runs the machine. No capture of this server carries it.
Tools