SCRYDOSBox-XReferenceSessionstartAlso in MAME
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
Start Bricks in a window I can watch without losing my keyboard, for at most fifteen minutes, and keep its log.
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"){
"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
{
"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 truewhen 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
truemakes the window fill the display; DOSBox-X then captures the mouse, so its pointer no longer follows yours. Needsshared=true.- size string, optional
- The window's size as
WIDTHxHEIGHT, in the host's unit. Needsshared=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-setof the same key wins. - break_on_int3 boolean, default
false truealso stops at the program's ownint 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, whichlogandlog_waitread. A file already there is overwritten. - capture_video boolean, default
false truerecords the run ofprogramas video. It needsprogram.- captures_dir string, default
"" - Where the emulator writes a capture it takes itself. Left empty,
captureunder the working directory. - plan array of object, optional
- A list of calls to run right after the start, each
{"op": <tool>, ...arguments}, run asperformruns a list. - settle_seconds number (>= 0, <= 600.0), optional
- How long each wait of the
planmay 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_writesaves into, which stays afterclose. Left empty, the session's temporary folder, deleted atclose. - binary string, default
"" - The DOSBox-X to run: an executable, or on macOS a
.appbundle holding one. Left empty,DOSBOX_X_BINARY, else thedosbox-xon the PATH. - background boolean, optional
trueopens the window behind your other windows and leaves the keyboard focus where it is;falseopens it in front. Left out, behind unlessshared.- presence boolean, default
true - Draws a border around the emulator's window while the session is open, brighter while a call runs the machine.
falseleaves it off. - dos_calls boolean, default
false truerecords every DOS call (INT 21h) the program makes, forlog(channel="dos"). It needs a build whose debugger hasDOSTRACE.- log_categories object, optional
- DOSBox-X's own
[log]categories, each with its level, written intologfile. It needslogfile. - guest_files array of string, optional
- Up to 16 files on the host that the program is expected to leave.
guest_fileandclosesay 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_loadloads 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
startarguments, 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. Itsfrontistruewhen 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; andchecked, what comparing it with the executable beside it found. - profile
- With a start profile: its
name, itsfile, andsupplied, 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
- A session is already open (
session_live). conf,cwdorsession_secondsgiven neither by the call nor by a start profile, or a path that is not absolute (bad_argument).- A conf, a
cwdor alogfilefolder that does not exist, or asymbolstable the executable beside it contradicts (bad_argument). display,fullscreenorsizewithoutshared=true, or adisplaythe host does not have (bad_argument).- A
sizethat does not fit the display, comes withfullscreen, or is ignored by the conf'ssdl output(bad_argument). fullscreenundersdl output=surface, or on macOS on a display other than 0 (bad_argument).flagsthat set what a named argument owns, or a-setglued to its value or without=(bad_argument).capture_videowithoutprogram,log_categorieswithoutlogfile, aninput_portfrom 1 to 1023, orguest_filesnaming a folder, a file twice or more than 16 (bad_argument).- A
profilethat no.scry/folder searched holds;searchedlists them (bad_argument). dos_callson a build whose debugger has noDOSTRACEcommand (no_channel).- A window that never appears on the display asked for. The session stays open for
windoworclose(window_not_visible). - A DOSBox-X that exits or never reaches its debugger (
session_broken).
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
-setofsdl display,sdl fullscreen,sdl windowpositionorsdl windowresolution, and-fullscreen. - A
-setvalue with spaces is one token. A-setglued to its value is refused because DOSBox-X hangs on it. - A
-setwithout=is refused because DOSBox-X ignores it with no error, and the setting would not apply. key=valuewith 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 afterAUTOEXEC.BATand cannot keep a session open.
The program and its symbols.
programloads the input helper itself when the conf's autoexec does not run it. A copy ofSCRY.COMin the conf that speaks another protocol is reported in thenote.- A
symbolstable is compared with the executable beside it before anything starts.symbols.checkedsays 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_placedholdsplaced,path,load_segmentin real mode,baseandloaded; a refusal isplaced: falsewithcodeandwhy.base_from=programis the DOS load segment of a real-mode program. For a DJGPP COFF executable it is the selectorCSholds at a protected-mode stop, where the code runs.break_on_int3has two limits that are the debugger's: anint 3at the reset vector faults, and one at the address of a stop is stepped over byresume.guest_filesanswers each file aspathandbefore, 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_dirandstate_dirare created with their parents.state_dirin the reply is the folder in use.shared,ready_after_s,argv,binary,binary_origin,version,backgroundandpresencesay what the launch used.- A
versionthe build would not give isavailable: falsewith awhy, and never fails the start. rearm_refusedsays 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
logfiledoes. logfileis 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
debugalog_categoriescategory can write a line per event:fileswrites one per read once the[log]settingfileiois on. Turn on only what the question needs. - The border never changes another reply: a failure to draw it shows only in
presence, instartandstatus. - While the debugger does not answer, the border is not redrawn. It catches up once a call is answered.
Related tools
The contract your client receives
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.