PC DOS Reimagined

Read the Blog, check out the Preview, see a few of the original Demos, and then Download the current release.

Download

The first BASIC-DOS release diskette is a bootable 360K diskette with BASIC-DOS, a “basic” set of utilities, a collection of BASIC samples (all from PC DOS 1.00), and a few demo programs. See it running on the BASIC-DOS Release page, or download BASICDOS-360K, a diskette image that most PC emulators can boot, or which can be written to a genuine 360K diskette.

When we say that BASIC-DOS comes with a “basic” set of utilities, we mean that both figuratively and literally, because while some are written in assembly language, most are in fact written in BASIC, including CHKDSK, FORMAT, MODE, and more. BASIC-DOS takes its commitment to BASIC integration, performance, and ease-of-use very seriously.

Project Status

BASIC-DOS began as a technology demo: a reimagining of what the first IBM PC operating system could have been, with a unified DOS and BASIC command interpreter, preemptive multitasking sessions, and other features that PC DOS wouldn’t offer for years (if ever). The goal now is to turn it into a usable product.

It is not a goal to provide every PC DOS function, or to be 100% compatible with PC DOS. BASIC-DOS implements what its own commands and BASIC programs need, plus enough of the PC DOS API to run typical DOS programs, so unchecked items below are possibilities, not commitments.

This section tracks what’s been completed ([x]) and what remains ([ ]). Items marked partial work, but with known gaps.

Boot and System Configuration

• Boot sector that loads the BASIC-DOS drivers, kernel, and interpreter
• Boot prompt when a hard disk is detected (press Esc within 2 seconds to boot from it)
• Booting BASIC-DOS from a hard disk partition (eg, a disk built with pc.js --sys=bd:2), which becomes the default drive
• CONFIG.SYS support for AUX, BUFFERS, CON, CPU, DEVICE, FILES, MEMSIZE, PATHCHAR, PRN, RING, SESSIONS, SHELL, SKIP, and SWITCHAR
• CON, AUX, and PRN are names for each session’s console, AUX, and PRN devices rather than drivers: CON= defines each session’s console (VKD$ or a serial port), and AUX= and PRN= choose any device (COM1 and LPT1 by default); without one (eg, no LPT1), opening the name fails, and its handle stays reserved
• SKIP= lists built-in drivers (by their exact device names, separated by commas) that should not be loaded (eg, SKIP=VKD$,FPU$); a skipped driver is never initialized, and its memory is reclaimed (CPU$, which manages memory, can’t be skipped)
• Installable device drivers (DEVICE=)
• Critical (“hard”) error handling: block device errors go to the session’s INT 24h handler (called on a DOS stack, with PC DOS inputs and responses), and the default handler displays the traditional “Abort, Retry, Ignore, Fail?” prompt (see Critical Errors)

Device Drivers

• VKD$ (video and keyboard), with multiple console contexts (one per session)
• COM, LPT, NUL, CLOCK$, and PIPE$ devices
• CPU$, loaded first, detects the processor and manages all memory, with the same functions in either mode: using a table of physical memory blocks and protected-mode descriptors on an 80286 or later with extended memory, and otherwise an MCB chain (see The CPU$ Drivers)
• CLOCK$ starts with the BIOS time of day and, on a PC AT, the real-time clock’s date
• DEBUG.COM, which loads as a driver on a serial port (see the demo) or runs as a program (DEBUG [program [arguments]]), with an 80286 disassembler, single-stepping (T, TR, and P), 9 breakpoints plus a temporary one, exception traps and reports of software interrupt functions (VT; eg, disk reads and writes, and DOS file functions), SYMDEB-style memory dumps, memory and register editing, loading disk sectors (L, as a program), and on an 80286, support for either mode
• MOUSE$, a serial mouse driver (loaded only if a Microsoft-compatible mouse responds on a COM port at boot), with a minimal INT 33h interface (functions 00h-04h, 07h, 08h, and a BASIC-DOS function that returns queued button events), and a pointer drawn in MDA and CGA modes that preserves anything drawn over it
• Interrupt-driven, asynchronous I/O for VKD$ and COM (COM ports also report how many bytes are waiting, with IOCTL_INSTATUS, for BASIC’s EOF, LOC, and INPUT$)
• Non-ASCII keys (eg, cursor and function keys) are returned as a zero followed by the key’s scan code, as in PC DOS (for VKD$, and for VT100 terminals on COM ports), so INKEY$ sees them as BASICA programs expect (eg, F10 in COMM.BAS); the DOS line editor maps the keys it uses to its editing keys, and raw keys mode only turns hotkeys like CTRL-C into ordinary keys
• Floppy disk reads, including multi-track requests and requests that cross 64K boundaries
• Floppy disk writes
• Media check and BPB rebuilds (reads PC DOS 1.x and 2.x diskettes)
• partial: Hard disk reads and writes (HDC$), for the FAT12 and FAT16 primary partitions of up to two PC XT or PC AT hard disks, which become drives C:, D:, etc. (drives A: and B: are always reserved for diskettes); a disk with no FAT partitions (eg, a new disk) is still given a drive letter (with “unknown media”), and IOCTLs return its geometry and partition table (IOCTL_GETPART) and write a new MBR with the driver’s own boot code (IOCTL_SETPART), so that FORMAT can partition it
• Diskette formatting: IOCTL_SETPARMS gives a volume its BPB (so that an unformatted diskette can be written) and IOCTL_FORMAT formats and verifies a track, with the DPT’s sectors per track set from the BPB (for every diskette transfer, so 8-sector diskettes read correctly, too); see FORMAT.BAS under Utilities

Protected Mode

On an 80286 or later, BASIC-DOS runs in protected mode; it’s built and tested for the IBM PC AT, and an 80386 runs the same code. See Protected Mode for details, and the Protected Mode demo to try it.

• BASIC-DOS switches to protected mode while its drivers initialize, and stays there, given at least 128K of conventional memory and 64K of extended memory; otherwise, or with CPU=8088 in CONFIG.SYS, it runs in real mode, as on an 8088
• COMMAND.COM, BASIC programs, and every program they run at ring 3 (unless CONFIG.SYS has RING=0), with each session’s memory in its own LDT, so a program can’t write to memory that isn’t its own
• A ring 3 program’s CTRL-C, critical error, and interrupt handlers run at ring 3, too (interrupt handlers see only the interrupts that ring 3 code in its session issues)
• A ring 3 program can free or resize only its own memory blocks, whose selectors always fit their lengths, and a bad pointer, stack, or return address ends the program, rather than stopping the system
• A ring 3 program can hook only the exception vectors it can handle, INT 21h, and INT 60h-67h, and can’t change the kernel’s record of its parent, stack, or handlers by writing its PSP
• COM and NE programs (eg, PRIMES.EXE) run in protected mode
• MASM 4.00 in TOOLS on the hard disk is converted from MZ to a dual MZ/NE executable that runs at ring 3 in protected mode and through its original MZ image in real mode
• Exceptions: a fault in a program’s own code ends that program with CPU fault nn (EC=nnnn) at nnnn:nnnn (ERRORLEVEL 255), as a divide error does; anywhere else, CPU$ prints the same line and System halted, and stops the machine, unless DEBUG.COM is loaded as a driver and takes over (see Faults)
• DEBUG.COM as a driver can stop and resume ring 3 programs with all of its commands; as a program, it runs at ring 3 with fewer commands
• Ring 3 for the programs that still need RING=0: those that hook an interrupt issued by ring 0 code (eg, INT 1Ch or INT 13h), call CPU$ (eg, CPUTESTS), or use IN, OUT, CLI, or STI
• MZ EXE files in protected mode, which fail with “Unable to load” (currently NOT under consideration for inclusion in BASIC-DOS, since NE programs take their place; see Limitations)
• 80386 features: virtual-8086 mode, paging, and 32-bit segments

Kernel: Processes, Memory, and Sessions

• COM and EXE program loading, PSPs, EXEC, and exit codes
• Memory allocation (through CPU$, which uses MCBs on an 8088), from all of memory (on an 80286 in protected mode, conventional and extended memory alike, and MEM and FRE count all of it), including per-program heap requests, and allocation from the top of memory (MCBTYPE_HIGH), which the interpreter uses for its own blocks so that the memory below them stays contiguous
• DOS_UTL_QRYMEM queries any memory block (its size in bytes, since a block can be 1Mb or more)
• INT 2Bh utility functions numbered contiguously (00h-28h) and grouped by purpose (see the Technical Reference)
• Preemptive multitasking of multiple sessions; a session closes when its last program ends (eg, EXIT in its shell), and the system halts when no session is left
• CTRL-C/CTRL-Break handling, CTRL-ALT-DEL session aborts, and divide and overflow errors, which end the program (as MS-DOS does) without aborting its parent (vectors 00h, 08h, 09h, 1Bh, and 1Ch that a terminated program left hooked, like MSBASIC’s, are restored)
• Session END: abort the current program in a specified session, interrupting any pending wait; WAITEND waits for the session to close
• Environment segments for EXEC (EPB_ENVSEG; zero inherits the parent’s), and COMMAND.COM gives every program an environment with COMSPEC and PATH
• TSR support (INT 27h and INT 21h function 31h; currently NOT under consideration for inclusion in BASIC-DOS)

Kernel: File System

• FAT12 and FAT16 file systems with read/write support
• Handle-based open, read, seek, IOCTL, and close
• Find first/next, disk info (free space), and current drive/DTA
• Handle-based file creation (function 3Ch) and writing (function 40h)
• File deletion (function 41h) and renaming (function 56h)
• FAT cluster allocation and freeing
• Write-back of modified FAT and directory buffers (every FAT copy is updated), including when the buffer is reused, on file close, disk reset, and restart
• FCB support: open, create, close, sequential, random, and random block reads and writes, find first/next, delete and rename (with wildcards), file size, set relative record, and filename parsing (functions 0Fh-17h, 21h-24h, and 27h-29h), including extended FCBs and device names
• Truncating/extending a file with a zero-length write (function 40h, and FCB function 28h)
• Subdirectories: paths (separated by \, or / when PATHCHAR is /) in all file functions, MKDIR and RMDIR (functions 39h and 3Ah), subdirectories that grow as needed, and per-session current directories for every drive (CHDIR and GETCWD, functions 3Bh and 47h)
• Same-drive file and directory moves (function 56h): preserve contents and metadata, update a moved directory’s .. entry, retain active current directories, and reject moves into itself or a descendant
• Absolute disk reads and writes: opening a volume (eg, C:) as a file gives read/write access to its sectors, in place of INT 25h and INT 26h; a volume can also be created (ie, opened FOR OUTPUT) and opened when its media is unknown (eg, an unformatted diskette), with no critical error prompt, and IOCTLs on a volume handle go to the drive’s driver (with their errors returned to the caller)
• Configurable disk buffer cache (BUFFERS=2-32, default 3), with least-recently-used replacement for FAT sectors, directory sectors, and file reads of less than a sector; other file data is transferred directly by the disk drivers, with one request for each run of clusters that are next to each other on disk (a write allocates all the clusters it needs first, as in PC DOS)
• File attributes: a read-only file can’t be opened for writing, replaced, or deleted; getting and setting a file’s attributes (function 43h) and a handle’s time and date (function 57h, kept when the file is closed); and on every BASIC-DOS disk, BASDEV.COM and BASDOS.COM are read-only hidden system files and COMMAND.COM is a read-only system file; BASIC’s OPEN FOR RANDOM opens a read-only file for reading (as MSBASIC does)
• Extended disk partitions (currently NOT under consideration for inclusion in BASIC-DOS)

Command Interpreter: DOS Commands

• CD, COPY, DATE, DEL, DIR, EXIT, MD, MEM, RD, RESTART, TIME, TYPE, and VER (HELP is an external command; see Utilities)
• DIR listings begin with the volume label and the directory’s full path, as in DOS 2.x (FFIRST with attribute 08h finds only the volume label, and GETCWD with DL = FFh returns the path of the directory FFIRST searched)
• DIR /A lists hidden files (only the hidden attribute keeps a file out of DIR, so system files like COMMAND.COM are listed), DIR /S lists the matching files in every subdirectory, with a header and totals for each directory, and DIR /W lists only the names (eg, HELP.TXT, with the path character after each directory), in as many 16-character columns as the console has room for
• The prompt displays the current drive and directory (eg, C:\SUBDIR>), and switches use / (eg, TIME /P), as in PC DOS, unless SWITCHAR is - or PATHCHAR is /, in which case they use -
• Running COM, EXE, BAT, and BAS files, and loading programs into other sessions
• BAT and BAS files can run other BAT and BAS files and then continue (no CALL command required); a nested BAS file gets its own variables
• Pipes (|) and output redirection (> creates or truncates the output file, >> appends to it), including redirection at the end of a pipeline (eg, DIR | SORT > TEST)
• Input redirection (<) for the first command on a line, after its arguments and before any | or > (eg, SORT /R < NAMES.TXT > SORTED.TXT or SORT < NAMES.TXT | MORE)
• :> and :>> redirect the output of an entire line, including BASIC statements, where > means “greater than” (eg, PRINT "hello world" :> TEST), at the prompt and in BAT and BAS files
• At the prompt, a line of BASIC statements can end with a pipe (eg, FOR I=1 TO 100:PRINT 3.14^I:NEXT | MORE); the statements run once the rest of the pipeline has started, and a runtime error still ends the pipeline’s input
• Pipes after BASIC statements in BAT and BAS files (currently only at the prompt)
• A BAT or BAS file can be the first command of a pipeline (eg, LS | MORE): like a built-in command, it runs once the rest of the pipeline has started, so it can’t fill the pipe before anything reads it, and its ARG$ ends at the |; a deferred command that fails (eg, TYPE NOFILE | SORT) sets ERRORLEVEL to 1. A BAT or BAS file can’t come after a | (it would have to run in the first command’s session), so that’s an error (eg, DIR | TEST.BAS reports “Unable to open TEST.BAS”)
• COPY creates (or truncates) the output file, and refuses to copy a file onto itself
• COPY and TYPE read through a temporary block of up to 32K (or half of the largest free block, if that’s smaller), so that copying a file doesn’t take several disk transfers per sector
• A DOS command (internal or external) ends at a colon that begins a word, so other commands can follow it on the same line (eg, DIR *.BAS : PRINT "done"), at the prompt and in BAT and BAS files
• A command that fails (internal or external, eg, “Unable to find” or “Unable to open”) displays its message and sets ERRORLEVEL to 1, and a BAT or BAS file continues with its next command, as in PC DOS; a successful command sets ERRORLEVEL to 0, and a program’s non-zero exit code isn’t a failure (see Error Handling)
• Any DOS command that accepts a file name (eg, COPY, DEL, DIR, LOAD, SAVE, TYPE, CD, MD, RD), and any redirection (<, >, >>, or :>), also accepts a string variable whose value is the file name (eg, DIR D$, COPY CON NAME$, or DIR > F$), and quoted file names (eg, TYPE "TEST$"); expressions aren’t evaluated, so DEL reports a syntax error for anything after the file name (eg, DEL "TEMP" + N$); see Command Arguments for how BASIC statements and external commands differ
• External commands receive the values of string variables in their arguments (eg, FORMAT D$ or FIND S$ *.TXT), quoted if they contain spaces
• ECHO ON/OFF and the @ prefix in BAT files: every BAT file starts with ECHO OFF (unlike PC DOS, so BAT files behave like BAS files unless ECHO ON is used), echoed lines are displayed with a @ in front, and a leading @ is ignored at the prompt, too
• A BAS file run from the command prompt remains loaded when it ends, along with its variables (like MSBASIC), so it can be LIST’ed or RUN again; RUN reuses the program’s compiled code once it has all been compiled (even if CTRL-C stopped the last run), unless the program or its variables have changed since, so it starts immediately
• Resident and transient portions: before running a COM or EXE file, COMMAND.COM frees idle variable blocks and discards its transient portion (about 23K), restoring it when the program ends (from a copy at the top of free memory, if the program didn’t overwrite it, or else from COMMAND.COM); MEM includes the transient portion in its bytes available, and displays the smaller bytes for BASIC separately
• Filters: FIND (/C, /I, /N, /R, /V), MORE, SED (/I, /N), SORT (/R, /+n), TEE (/A), TR (/C, /D, /S), UNIQ (/C, /D, /I, /U), and WC (/L, /W, /C); FIND, MORE, SED, SORT, UNIQ, and WC also accept file names, FIND’s string and SED’s script need quotes only if they contain spaces, and every filter treats CTRL-Z as the end of input
• Regular expressions in the style of UNIX ed and sed (., [...], [^...], *, ^, $, \(...\)), shared by FIND /R and SED, whose scripts have line-number, $, and /regex/ addresses (and ranges and !) and the s (with &, \1-\9, g, and p), d, p, q, and = commands
• Pipelines with more than one filter (eg, TYPE FILE | SORT | MORE): when a session ends, its output pipe receives end-of-input
• Pipe reads return as soon as some data is available (like UNIX pipes), so a filter such as MORE displays a pipeline’s output as it’s produced, instead of a buffer at a time
• When any command of a pipeline fails (eg, a program that can’t be found, or no session available for it), the error is reported, the commands already running in other sessions are ended (DOS_UTL_END), and the first command never runs; and when a command stops reading a pipe early, the command writing to it gets a write error instead of waiting forever
• LIST VARS: list preserved strings (including PATH$), scalar values, and array dimensions in the current session
• PATH$: the directories searched for programs (eg, PATH$="A:\;A:\EXT;A:\DEMOS;A:\SAMPLES" on a SHELL line in CONFIG.SYS); unlike other variables, it survives NEW and CLEAR
• Every bootable BASIC-DOS disk has the same layout: BASDEV.COM, BASDOS.COM, COMMAND.COM, CONFIG.SYS, and AUTOEXEC.BAT (if any) in the root, utilities (including DEBUG.COM, and HELP.COM with HELP.TXT) in EXT, demo programs in DEMOS, and the PC DOS 1.00 BASIC samples in SAMPLES (test programs are on a separate diskette, in TESTS); the BASIC-DOS Release diskette, BASICDOS-360K, is also available as a raw 360K image; every disk has a volume label (eg, BD-D40), and every machine’s diskette list shows the BASIC-DOS diskettes by title (eg, “BASIC-DOS 40-Column Demo”); the 10Mb hard disk’s directories are in the same order as a diskette’s (EXT, DEMOS, and SAMPLES, followed by SRC, TESTS, and TOOLS), since pc.js’s --order option overrides its usual sorting
• REN: rename files and directories and move them between directories on the same drive
• Loading tokenized (binary) BAS files saved by BASICA or GW-BASIC (eg, the samples on the PC DOS diskettes): they’re converted back to text as they’re loaded (as LIST would display them), including MBF floating-point constants (converted to IEEE doubles and formatted by FPU$); protected BAS files are still rejected with “Invalid file format”
• Disk utilities are external programs; see Utilities

Utilities

Utilities live in the EXT directory of every BASIC-DOS disk. The filters, HELP, SLEEP, VI, and DEBUG are assembly language, but utilities that don’t need that speed are written in BASIC-DOS BASIC: clean, succinctly commented programs, with every line indented by a tab (after a line number only where one is needed as a label), the style in which BASIC-DOS lists programs. The interpreter is extended as needed to make them possible (eg, IOCTL #, and opening unformatted volumes, for FORMAT).

• partial: FORMAT.BAS (360K diskettes by default, /1 for single-sided, /8 for 8 sectors per track, and /S to copy the system files from the current drive), which formats and verifies each track through the diskette driver, builds the boot sector, FATs, and root directory using the PC DOS 2.x rules for cluster and root directory sizes (with 12-bit FATs, which PC DOS 2.x used whenever it could), and reports the space available; it refuses the current drive
• partial: FORMAT for hard disks: it displays the disk’s partition table first, formats one of its FAT volumes (asking which, when the drive given is the whole disk) after a warning, and when a disk has no partition table, offers to create one (with prompts, rather than a separate FDISK) with a single volume of the size requested in Mb (up to 32Mb), writing an MBR and formatting the volume (12-bit FAT up to 32680 sectors, as PC DOS 3.x did, and 16-bit FAT beyond)
• FORMAT.BAS: 720K and 1.2M diskettes (/F:720 and /F:1200, or by default, the drive’s own size, which the diskette driver’s IOCTL_GETPART reports on a PC AT), with PC DOS 3.x’s layout for 1.2M, and volume labels (/V or /V:label); since a colon in a DOS command can now follow a switch’s letter, switch values like /F:720 work in BAS and BAT files, too
• CHKDSK.BAS (checks every cluster chain, and reports cross-linked files, allocation errors, invalid clusters, lost clusters, and disk space, without fixing anything), COMP.BAS, DISKCOPY.BAS (formats the target as it copies, with multiple passes for single-drive copies), HEXDUMP.BAS (DEBUG’s DB format, with /S and /N), LABEL.BAS and VOL.BAS (writing the label entry directly), SYS.BAS, and TREE.BAS (with /F and /A)
• ATTRIB.BAS: displays the attributes (R, H, S, and A) of the matching files, including hidden and system files, after setting (+) or clearing (-) any that are given (eg, ATTRIB +R *.BAS), using the DOS statement
• LS.BAS: a UNIX-style ls, listing files and directories sorted, in columns down the console (or one per line when the output is a file or pipe), with a path character after each directory name, and /1, /a, /l, /R, /r, /S, and /t, which can be combined (eg, LS /ltr)
• Utilities report what they can’t handle: COMP compares any number of matching files (it used to stop silently after 201), TREE and LS display Too many subdirectories and Too many matching files, CHKDSK names any directories it doesn’t check and doesn’t report lost clusters in that case, and FIND, WC, and other filters reject more than 8 file names with Syntax error; COMP also sets ERRORLEVEL to 1 if any comparison fails, and CHKDSK if it finds problems or can’t check everything
• Consistent BAS utility arguments: switches start with the switch character (eg, - after SWITCHAR=-), and a missing or invalid argument, such as an unknown switch (which CHKDSK, FORMAT, and TREE used to ignore), displays Syntax error
• Every command rejects switches it doesn’t accept with Syntax error, in any position (internal commands from COMMAND’s table of switches, and assembly utilities from their own lists), so that a mistyped switch can’t silently change what a command does; usage text lives only in HELP.TXT, which HELP displays as Usage:, a blank line, and the rest of the entry
• An internal command after a pipe (eg, VER | DIR), which used to hang, displays Syntax error, since internal commands don’t read their input
• END n sets ERRORLEVEL (0 if n is omitted), and the BAS utilities use it to report failures
• Switches can appear anywhere on a command line (including VI’s /WS, and COPY’s /B, which is accepted for compatibility with PC DOS and does nothing, since COPY always copies and concatenates entire files)
• MODE.BAS: display columns and color (MODE 40, 80, BW40, BW80, CO40, CO80), serial ports (eg, MODE COM1:9600,N,8,1, which sets the port by opening it with those parameters and no input buffer), and printer columns and lines per inch (MODE LPT1:132,8)
• HELP.COM: HELP is an external command, which reads HELP.TXT from the EXT directory of the drive COMMAND.COM was loaded from (normally the boot drive), so that COMMAND.COM’s core is 963 bytes smaller and low memory systems have more room for BASIC programs; KEYS is now HELP KEYS
• VI.COM: a full-screen text editor with a subset of the commands of the UNIX vi editor (and WordStar keys with /WS), for VKD$ consoles and ANSI or VT100 serial consoles, and files of up to 64K
• Additional FORMAT features: adding volumes to a partitioned disk, verifying hard disk sectors, and marking bad clusters
• Other PC DOS-inspired utilities possibly written in BASIC: DISKCOMP and PRINT (background printing, using a session), and CHKDSK /F (ASSIGN, BACKUP, EDLIN, JOIN, RESTORE, and SUBST are currently NOT under consideration for inclusion in BASIC-DOS)
• Additional third-party tools (eg, PKZIP and PKUNZIP) added to the TOOLS directory

Command Interpreter: BASIC Language

• 32-bit integer variables, constants, and expressions (including AND, OR, XOR, EQV, IMP, NOT, MOD, and shifts)
• Type suffixes (% for integers, # or ! for doubles, and $ for strings), where the type is part of a variable’s identity (eg, after DEFINT A-Z and then DEFDBL A-Z, A is a new variable, separate from A%), and on numeric constants (eg, 1.5#, 2!, and 7%)
• String variables, concatenation, and comparisons
• String functions: ASC, CHR$, DATE$, FRE, HEX$, INKEY$, INSTR, LCASE$, LEFT$, LEN, MID$, OCT$, RIGHT$, SPACE$, STR$, STRING$, TIME$, UCASE$, and VAL
• String pool management: temporary strings are released as soon as they’re consumed, strings are compacted (and empty string blocks freed) when space runs out, and runtime string errors (eg, “String too long”) abort the program cleanly
• CLS, COLOR, DEF FN (including string functions and parameters), DEFDBL, DEFINT, DEFSTR, ECHO, GOTO, IF/THEN/ELSE, LET, PRINT, REM (and ' remarks), and RETURN
• Assignments without LET, in BAS and BAT files and at the prompt
• LOAD, LIST (which shows each line as SAVE writes it, so tabs line up as they do with TYPE), NEW, RUN, and SAVE
• Entering programs at the prompt: a line that begins with a line number is added to the loaded program (in line number order, replacing any line with the same number), and a line number by itself deletes that line; AUTO, DELETE, EDIT, and LIST with line ranges (eg, LIST 100-200) work with program lines, too
• Functions: ARG$ (command-line arguments of a BAS or BAT file), DIR$ (file searches, returning each match’s attributes, time, date, size, and name), ERR, ERRORLEVEL, MAXINT, PEEK, RND, and RND%
• Arrays of integers, doubles, and strings, with up to 255 dimensions: DIM, ERASE, OPTION BASE, automatic dimensioning (with a largest subscript of 10) of arrays used without DIM, and “Subscript out of range” and “Duplicate definition” errors
• Control flow: END, FOR/NEXT (with STEP, and integer or double loop variables), GOSUB/RETURN, ON … GOTO/GOSUB, STOP, and WHILE/WEND
• Memory management that’s forgiving of low or fragmented memory: code, text, variable, and string blocks are modest (4K) blocks that are chained together as needed (generated code continues in another code block via a far JMP), no block type takes more than a quarter of the largest free block, and smaller blocks (down to 512 bytes) are used when necessary
• DATA, READ, and RESTORE (DATA items are found in the program’s text as READ needs them)
• MOUSE ON/OFF and the MOUSE(n) function (modeled on MSBASIC’s PEN), which returns button events, their positions, and the current position and buttons, in pixels (graphics modes) or columns and rows (text modes); the pointer is hidden while graphics statements run (until the next MOUSE function), and the mouse is turned off when a BAS program ends
• INPUT and LINE INPUT, from the keyboard or an open file
• &H and &O prefixes in VAL (& alone also means octal)
• PRINTF [#n,] USING: formatted output with C-style % specifiers (eg, PRINTF USING "%5.2f";X#), plus specifiers for the parts of packed dates and times (eg, %.3F %2D %Y)
• Sequential file I/O: OPEN FOR INPUT, OUTPUT, and APPEND, CLOSE, PRINT #, WRITE #, INPUT #, LINE INPUT #, EOF, LOC, and LOF
• Random access file I/O: OPEN FOR RANDOM with LEN, FIELD, LSET, RSET, GET #, PUT #, and binary conversion functions (CVI, CVL, CVD, MKI$, MKL$, and MKD$)
• Consistent invalid drive errors: a drive that doesn’t exist is simply “Invalid drive”, whether it’s selected at the prompt (eg, Z:), named to a command (eg, DIR Z:), a program (eg, Z:X), a filter (eg, WC Z:X), a BAS utility (eg, VOL Z:, which used to say that the drive had no label), or DEBUG; in BASIC, it’s runtime error 77, which DIR$, OPEN, CHAIN, and the DOS statement all report
• IOCTL #: sends an IOCTL request (with a numeric value in CX and DX, or a string’s data) to the device or volume open as a file, with driver errors reported as runtime errors (eg, “Permission denied” for a write-protected diskette); IOCTL$ returns the data (up to 255 bytes) a driver stores in response to a request

• [x] DOS ax[,bx[,cx[,dx

  string]]]: calls DOS (INT 21h) with those registers (a string is passed as DS:DX, null-terminated), with DOS errors reported as runtime errors (eg, “File not found”); DOS(n) returns the registers that DOS returned (eg, attributes from function 43h); used by ATTRIB.BAS and FORMAT.BAS

• Error handling (ON ERROR GOTO, ERROR, ERR, ERL, and RESUME line, with any active GOSUBs intact, and “Division by zero” for integer division; see the BASIC Samples checklist); RESUME [0] and RESUME NEXT aren’t supported (see Non-features)
• Specific error messages for compile-time errors: “NEXT without FOR”, “FOR without NEXT”, “WHILE without WEND”, “WEND without WHILE”, and “Type mismatch” (formerly all reported as syntax errors), with the line of the FOR or WHILE for an unclosed loop, and no “in line 0” for commands typed at the prompt
• Runtime error messages for numeric errors
• STOP’s “Break” message (STOP is currently the same as END)
• The MID$ statement (ie, MID$(A$,N[,M]) = B$), with string variables or array elements
• Comma print zones in PRINT (commas currently print a tab)
• RUN file (eg, RUN "MENU", which BASICA programs use to run another program): at the prompt, it loads and runs the BAS file; in a program, it replaces the program, as CHAIN does, and closes any open files; file can also be unquoted or a string variable, like other DOS commands’ file names (RUN line and the R option aren’t supported)
• RUN in a program restarts it, as in MSBASIC (clearing its variables and closing its files), instead of running it again inside itself
• INPUT$(n[,[#]f]) (reading characters from the keyboard without ENTER, or from a file or serial port)
• Devices in OPEN, as in MSBASIC: “SCRN:”, serial port settings (eg, “COM1:300,E,7,1”), a device opened without FOR for both input and output (with EOF and LOC reporting a serial port’s waiting input), and “Device unavailable” for a missing device; and file statements without a space before the # (eg, PRINT#1)
• KEY n,string and WIDTH device,width are accepted (function keys always return their key codes, and device output is never broken into lines)
• BEEP
• TIMER (seconds since midnight, with hundredths, or whole seconds without FPU$)
• LPRINT, through PRN (LPT1 unless CONFIG.SYS has a PRN= line), which prints with the BIOS (no PRN device is a “Device unavailable” error)
• LLIST and LPOS, and printer errors (“Device timeout”, “Out of paper”, and “Device fault”) for LPRINT, LLIST, and PRINT # to a printer
• TRON and TROFF (line tracing), and CONT (continuing after STOP or CTRL-C)
• Event trapping: ON TIMER(n), ON KEY(n), ON STRIG(n), ON PLAY(n), and ON COM(n) GOSUB, with TIMER, KEY(n), STRIG(n), PLAY, and COM(n) ON, OFF, and STOP
• BLOAD and BSAVE (eg, saving and loading screen images with DEF SEG)
• CHAIN replaces the running program, as in MSBASIC, with CHAIN MERGE, a starting line number, and ALL (keeping all variables), and MERGE merges a file’s lines at the prompt
• COMMON (passing selected variables to a CHAINed program) and CHAIN’s DELETE option
• Low-level features: INP, OUT, WAIT, VARPTR, VARPTR$, CALL, USR, and DEF USR (machine language routines), and STICK and STRIG (joysticks)
• Limitations of BASIC-DOS-specific features: multi-line DEF functions must fit in a single code block, function blocks end at the first RETURN (ie, RETURN can’t be conditional), and each array requires a single block (64K max)

Floating-Point

BASIC-DOS will support only one floating-point type: IEEE 754 64-bit (double-precision) values. It won’t use any MBF (Microsoft Binary Format) code.

• Parser support for floating-point constants (CLS_FLOAT tokens)
• Numeric variables default to doubles (unless DEFINT is used)
• MBF-based MSLIB option removed
• FPU$ device driver, which detects an 8087 at boot and provides a table of floating-point functions (IOCTL_GETFPU), which run at their caller’s privilege level (in protected mode, through conforming code selectors), while the kernel saves and restores each session’s 8087 state when it switches sessions
• 8087 functions: arithmetic (including ^), comparisons, conversions between longs and doubles, ABS, INT, FIX, and SQR
• Software emulation of all FPU$ functions for systems without an 8087
• FPU$ unloads itself on a machine with 64K of memory or less (as if CONFIG.SYS had SKIP=FPU$), leaving that memory for BASIC programs
• The interpreter reports at startup whether floating-point uses an 8087, emulation, or is disabled (no FPU$ driver); when disabled, variables default to integers and “/” and “^” are integer operations
• String-to-double (FPU_ATOD) and double-to-string (FPU_DTOA) conversions, and %f support in sprintf
• Expression generator support for mixed integer/floating-point operations (promotion and demotion rules), using FPU$ calls
• Floating-point constants and PRINT output in BASIC programs
• BASIC math functions: ABS, ATN, COS, EXP, FIX, INT, LOG, SIN, SQR, and TAN
• FPUTESTS, run with and without an 8087 by tools/tests/quick.sh
• Fast software emulation: doubles are unpacked and packed in registers, division uses the 8086’s DIV (16 bits at a time), multiplication sums its partial products a column at a time, and SIN, COS, TAN, ATN, LOG, and EXP use fdlibm’s minimax polynomials; arithmetic results match the 8087 bit for bit, and math functions are within 1 ulp (see the benchmarks)
• STR$ formats integer values directly, without floating-point conversions
• Unused floating-point utility function stubs (DOS_UTL_ATOF64, DOS_UTL_I32F64, and DOS_UTL_OPF64) removed, since FPU$ supersedes them
• Better error reporting for FPU exceptions

BASIC Samples

The poster child for BASIC samples support is DONKEY.BAS, from the original IBM PC DOS 1.00 diskette. DONKEY.BAS was our initial test candidate for BASIC-DOS’s compatibility with IBM PC BASIC programs. These are the items it needed, followed by related work that remains. Originally, BASIC-DOS compiled an entire program before running it, so there was a startup delay, and every statement had to be recognized, even those that DONKEY.BAS did not immediately need (eg, PLAY and CHAIN). However, BASIC-DOS now performs incremental compilation, so those are no longer concerns.

• SCREEN 0, 1, and 2 (text, 320x200, and 640x200 modes), WIDTH 40 and 80, and LOCATE (row, column, and cursor visibility)
• VKD$ driver IOCTLs to get and set the video mode and cursor position; a mode change (whether by IOCTL or by INT 10h directly) turns the console into a full-screen, borderless context that uses INT 10h passthrough, so text output and CLS work in graphics modes
• COLOR with blinking foregrounds (16-31), omitted arguments (eg, COLOR ,1), and SCREEN 1’s background and palette
• KEY ON and KEY OFF (accepted, but no-ops, since BASIC-DOS doesn’t display function keys)
• DEF SEG, PEEK, and POKE (DEF SEG alone selects BASIC-DOS’s own data segment, so DONKEY.BAS’s POKE 106,0 is harmless)
• RND as a floating-point function (0 <= RND < 1); RND% still returns an integer
• String constants with no closing quote at the end of a line
• ON ERROR GOTO (and GOTO 0), RESUME line, ERROR, and ERR, with MSBASIC’s error numbers for runtime errors
• PLAY (notes, N, O, <, >, L, P, T, MN/ML/MS, X, dots, and semicolons; MF/MB are ignored, since music always plays in the foreground)
• SOUND frequency,duration
• CHAIN file (now replaces the running program; see CHAIN MERGE above)
• PSET, PRESET, LINE (including LINE -(x,y), B, BF, and an omitted color), PAINT, and DRAW (U, D, L, R, E, F, G, H, M, B, N, C, and S), drawing directly into CGA memory in modes 4-6
• GET and PUT (PSET, PRESET, XOR, OR, and AND), using integer arrays (passed by name) in BASICA’s image format, with one 16-bit word per element, so programs that build images by hand (like DONKEY.BAS’s B%) work
• Syntax errors report the program’s line number (eg, “Syntax error in line 1160”) instead of the line’s position in the file
• DONKEY.BAS runs (see the single-session demo, whose diskette has all the samples)
• Performance: PUT and GET copy whole bytes (shifting and masking each row in registers), horizontal lines, BF, and PAINT fill whole bytes, and the video mode is cached, so graphics statements make no driver or BIOS calls; SOUND returns immediately (as in MSBASIC, the next SOUND waits for it to finish, and the CLOCK$ driver turns it off), so DONKEY.BAS is paced at one loop per tick, like MSBASIC
• CIRCLE (for CIRCLE.BAS, one of the other PC DOS 1.00 samples on the demo disk), using MSBASIC’s algorithm and integer math (angles and aspects are converted from doubles without FPU$), so it draws the same pixels as MSBASIC, about twice as fast
• CLEAR (resets variables and erases arrays; its sizes are ignored)
• PAINT fills through pixels that already have the paint color (like MSBASIC), so it draws the same pixels as MSBASIC; it scans rows a byte at a time (using tables of each byte’s boundary and paint-colored pixels), and its seeds remember their direction and parent span, so it never rescans the row it came from, making it faster than MSBASIC’s
• A BASIC keyword typed alone that isn’t a valid statement (eg, CIRCLE) runs the program with that name (eg, CIRCLE.BAS)
• LINE (and DRAW and CIRCLE’s lines to the center) use MSBASIC’s line algorithm, so they draw the same pixels as MSBASIC, but lines whose endpoints are on the screen are drawn by stepping the video address and pixel mask directly (about 4 times faster than before)
• When a BAS program that used a graphics mode ends (or is aborted), its video mode is restored (undoing any SCREEN or WIDTH, as DONKEY.BAS needs), while text-mode changes alone (eg, WIDTH 40) persist, as in MSBASIC (and as MODE.BAS needs), and when a console returns to its original mode, its original geometry (eg, its border) is restored, too
• More performance: text output in graphics modes goes through the VKD$ driver and the BIOS
• Graphics features that the samples don’t use: STEP coordinates (every point becomes the last point referenced, as in MSBASIC), POINT, DRAW’s A, TA, P, and X commands (A uses MSBASIC’s integer arithmetic, so it draws the same pixels), PLAY’s X command and semicolons, and GET/PUT with double arrays (in MSBASIC’s raw byte format)
• MORTGAGE.BAS, one of the PC DOS 1.00 samples, with its PRINT USING statements changed to PRINTF USING (see How to replace PRINT USING)
• CALENDAR.BAS, one of the PC DOS 1.00 samples, which builds each month with the MID$ statement and prints the year with LPRINT (its February always has 28 days, as in BASICA, since it compares its year index, 1-9, with 1984 and 1988)
• MUSIC.BAS, one of the PC DOS 1.00 samples, which loads each song with CHAIN MERGE, and the samples’ CHAIN file,line back to SAMPLES.BAS (their menu)
• COMM.BAS, one of the PC DOS 1.00 samples, a terminal program for a serial port (using KEY n,””, WIDTH “COM1:”,255, OPEN “COM1:…” and “SCRN:”, PRINT#, EOF, LOC, and INPUT$), with its RESUME statements changed to RESUME line (see RESUME)
• The rest of the PC DOS 1.00 samples: SPACE.BAS’s delay loops are too fast to see its flying saucers
• Later BASICA and GW-BASIC graphics: VIEW, WINDOW (world coordinates, which POINT, PMAP, STEP, and CIRCLE’s radius use, too), PMAP, and PAINT with tile patterns
• PCOPY (which needs SCREEN’s active and visual pages first)
• Keeping other sessions on the same adapter from writing to the screen while it’s in another mode; also, the VKD$ driver restores the BIOS’s video data after every INT 10h call, so programs that read the BIOS’s video mode (0:449h) may see a stale value

Build, Tests, and Documentation

• Builds with MASM 4.0 using mkdos.sh (PC.js and MS-DOS 3.20), which builds the binaries that package.json’s config.release property selects by default (final for release binaries, or debug for DEBUG binaries, with run-time assertions; mkdos.sh final or mkdos.sh debug overrides it), using its version property’s major and minor numbers as the BASIC-DOS version, and also updates the BASIC-DOS demo disks after a successful build
• Builds itself: mk.sh runs the same build tools on BASIC-DOS, producing identical binaries
• DOSTESTS: CALL 5, memory allocation, file create/write/read-back, file sharing, path character, and file rename/delete tests
• STRFUN and STRPOOL: BASIC string function tests, and string pool stress and leak tests
• ARRAYS: BASIC array tests (including leak tests)
• FLOW: BASIC control flow tests
• EXPRERR: invalid expressions (eg, string operators and optional function parameters) that must be syntax errors
• FILEIO: BASIC sequential and random access file tests
• RUNFILE: RUN tests (a missing file, and replacing or restarting the program, which clears its variables and closes its files)
• MOVES: file and directory moves, destination growth, sharing, and ancestry checks
• HARDERR: INT 24h compatibility tests (handler inputs, the stack switch, Retry, Fail, Ignore conversion, and Abort), using an empty drive B:
• R3TESTS: at ring 3, tests that misusing DOS (bad pointers, stacks, selectors, and vectors, and overwritten PSP fields) or using CLI or OUT ends only the program that did it, each in its own copy of the program
• Unattended test runs using tools/tests/quick.sh (boots BASIC-DOS with and without an 8087, and from a hard disk, runs FPUTESTS, DOSTESTS, BUFTESTS, STRFUN, STRPOOL, ARRAYS, FLOW, EXPRERR, CMDS, VARS, FILEIO, RUNFILE, PRTUSING, MOVES, ATTRS, FCBTESTS, HARDERR, IOERR, and PRINTF, and reports whether the tests passed)
• tools/tests/mmutest.sh runs the same floppy tests, plus CPUTESTS, on a PC XT, a PC AT with CPU=8088, and a PC AT in protected mode, with and without RING=0 (at ring 3, CPUTESTS and HARDERR’s interrupt hook tests are skipped), and R3TESTS with a second console
• CMDS: command tests (pipes, redirection, including to quoted and string variable file names, string variables and unquoted strings in external command arguments, TYPE, DEL, DEL’s extra arguments, invalid switches, TIME /D, HELP, SOUND, remarks, and hex constants)
• tools/tests/chkdsk.sh runs MS-DOS 3.20 CHKDSK on a diskette image saved by a test session (see QUIT /S in pc.js)
• BENCH.BAS and MICRO.BAS benchmarks, which run unchanged in BASIC-DOS, BASICA, and GW-BASIC (see the results); tools/tests/bench.sh runs BENCH.BAS in all six configurations (each with and without an 8087) and prints the results in seconds
• HELP for commands, functions, and constants (eg, HELP MID$), found by searching HELP.TXT, so new entries need no other changes; each entry is tagged with a category, so HELP ALL, BASIC, DISK, EXT, FUNC, and SYSTEM list the keywords of one category (HELP alone explains them)
• Demos for the IBM PC, PC XT, PC AT, and COMPAQ DeskPro 386, with one page per demo and machine, including a Monochrome demo on a 64K IBM PC and on a 640K IBM PC XT with the 10Mb hard disk, and a Terminal Only demo with no video adapter, whose only console is a VT100 on COM1, on a 64K IBM PC and on a 640K IBM PC XT with the 10Mb hard disk
• BASIC-DOS Manual: using BASIC-DOS, all commands and functions, programming, and configuration
• An alphabetical list of the files provided with BASIC-DOS, with a manual page for each utility that describes all of its switches, internal commands, and messages
• One syntax notation throughout the manual and HELP.TXT: italics for values you supply, [ ] for optional items, | between alternatives, ... for repetition, one line per form, and file numbers written #n (statements with both forms, like PRINT and PRINTF, have one entry with an optional [#n,])
• BASIC-DOS Technical Reference: architecture, DOS functions, utility functions, device drivers, the FPU$ interface, internal structures, and protected mode
• More tests (eg, BASIC language and COMMAND.COM tests)

Non-features

These aren’t project goals:

• PC DOS batch syntax, since BASIC-DOS uses BASIC for batch files: replaceable parameters (%1-%9), environment variables (SET), ECHO message, IF EXIST, FOR … IN … DO, SHIFT, and PAUSE. BASIC-DOS provides command-line arguments through ARG$, BASIC variables, PRINT, expressions, and control flow instead. See Batch Files for the differences and equivalents; this does not imply that every PC DOS batch operation already has a direct equivalent.
• INT 25h and INT 26h (absolute disk reads and writes), since opening a volume (eg, C:) as a file gives the same access to its sectors; see File Handles.
• RESUME without a line number (or with 0) and RESUME NEXT, which resume at or after the statement with an error, since BASIC-DOS compiles programs, and finding where the statement with an error (or the next one) begins would require recording where every statement’s code begins, making programs larger; RESUME line is supported, and a handler can use ERL to choose the line. The COMM.BAS sample on BASIC-DOS disks uses RESUME line instead; see RESUME.
• PRINT USING and LPRINT USING, since PRINTF USING covers the same needs with C-style % specifiers; see How to replace PRINT USING for the equivalents of its template formats (eg, ###.## is %6.2f). The MORTGAGE.BAS sample on BASIC-DOS disks uses PRINTF USING instead.
• CTTY (introduced in PC DOS 2.0), since BASIC-DOS already provides the ability to define multiple terminal-based sessions on serial ports using CON= in CONFIG.SYS; allowing a session to change its “personality” on the fly would cause more problems than it would solve, and would probably work about as well as CTTY did (ie, poorly).
• LOAD inside a running BAS or BAT file (it’s an error, “Not allowed in a program”, since it would replace the running file’s own text); programs that run other programs use RUN file or CHAIN instead.

Roadmap

These are the next steps, roughly in priority order:

1. Remaining string and input/output features (comma print zones)
2. The rest of runtime error handling (messages for numeric errors other than “Division by zero”, such as “Overflow”)
3. Common BASICA features that BASIC-DOS lacks: BEEP and COMMON
4. The rest of protected mode on an 80286 or 80386: ring 3 for the programs that still need RING=0 (interrupt hooks that DOS or the ROM BIOS calls, and CPUTESTS); see Limitations
5. Protected-mode versions of the remaining MZ-only build tools (MASM 4.00 is available now in TOOLS)

License

BASIC-DOS is an open-source project on GitHub released under the terms of an MIT License.

Copyright (c) 2020-2026 Jeff Parsons Released under MIT License