Skip to main content

DOT commands

DOT commands are small eSXDOS command-line programs invoked from 48K Spectrum BASIC with a leading dot. Spectranext loads compatible commands from the visible /bin directory of the current filesystem and runs them using an eSXDOS-compatible environment.

For example, if ls is available in /bin:

.ls

Command arguments follow the command name in the usual way:

.cd games
.more readme.txt

The command name is looked up case-insensitively. Files in /bin participate in the normal filesystem lookup rules: on XFS, a RAM copy can temporarily replace a committed or built-in command.

Command format and memory layout​

Spectranext supports the traditional eSXDOS DOT binary format.

  • The command is loaded into two 4 KiB RAM pages.
  • The first page is mapped at $2000–$2FFF.
  • The second page is mapped at $3000–$3FFF.
  • Execution begins at $2000.
  • The maximum command image is 7.5 KiB (7,680 bytes), leaving the upper part of the second page for command arguments and workspace.

The command receives its argument text in the standard DOT-command area in the second page. Commands should treat their program area as normal writable RAM: code, data, and temporary variables may share the loaded pages, subject to the size limit and the command's own layout.

eSXDOS calls from a command​

Compatible commands use the normal eSXDOS RST $08 interface for file and directory operations. Spectranext's DOT kernel stages the call safely, invokes its eSXDOS compatibility layer, and returns results in the expected eSXDOS form.

note

In DOT-command mode, eSXDOS operation calls use HL where the normal eSXDOS ABI uses IY. Assemble or adapt commands accordingly; do not rely on IY carrying the operation value while a DOT command is running.

The supported call set, drive behaviour, errors, tape input support, and filesystem limitations are documented in eSXDOS compatibility. Use that page as the compatibility contract rather than relying on a particular storage backend.

Output and BASIC interaction​

DOT command output is routed through the normal Spectrum display channel, so commands such as .ls and .more print in the expected place. A command returns control to BASIC when it completes; an error is reported through the normal BASIC/Spectranext error path.

The command itself is not a BASIC extension. It runs as an eSXDOS program and should use the eSXDOS APIs it expects, rather than assuming that ordinary BASIC variables or a BASIC parser are available underneath it.

Spectranext services while a DOT command runs​

warning

While a DOT command is running, it is in the eSXDOS compatibility environment. Spectranext socket and other native Spectranext operations are not available directly from DOT-command mode. The compatible filesystem calls continue to work because the eSXDOS layer bridges them to mounted Spectranext filesystems.

This restriction is about the execution environment, not about the filesystem. A DOT command can open a file from XFS, TNFS, or another supported mount through eSXDOS, but it cannot directly call the Spectranet socket jump-table API while its two command pages are mapped.

TAP programs are different​

Normal TAP programs do not use DOT-command paging. They can use the eSXDOS compatibility layer and call native Spectranext services, including socket operations, through the syscall jump table. That makes a TAP program the appropriate hand-off point when an application needs both eSXDOS-compatible file handling and Spectranext networking.

In practice: use a DOT command for a small filesystem-oriented command-line tool. If it needs sockets, protocol offload, or other native Spectranext APIs, have it load or launch a TAP program and transfer execution to that program.

See also​