BASIC-DOS

DOS Functions

BASIC-DOS provides a subset of the PC DOS 2.x function interface, through INT 21h, with the function number in AH. Unless noted otherwise, functions that can fail return with carry set and an error code in AX, and with carry clear on success. Programs can also use the CP/M-style CALL 5 interface.

Functions not listed below (including any function above 57h) aren’t implemented, and return with carry set and AX = ERR_INVALID.

The DOS_* names are defined in dosapi.inc (define DOSFUNC before including it).

Function Summary

Console

The line editing keys that 0Ah supports are described in Typing Commands.

Disks and Directories

File Handles

Handles 0-4 are the predefined handles STDIN, STDOUT, STDERR, STDAUX, and STDPRN. Filenames can also be device names (eg, CON, NUL, or COM1), optionally followed by a colon and device-specific parameters (eg, CON:40,25).

A file can be open more than once for reading, but a file opened for writing (MODE_ACC_WO or MODE_ACC_RW, which includes every file opened with 3Ch) can’t be open anywhere else. Opening a file in a way that would violate that rule fails with ERR_SHARE, as does deleting (41h) a file that’s open. Unlike PC DOS 3.x, BASIC-DOS doesn’t need SHARE for this, and it ignores the MODE_DENY_* bits for files. Devices are exempt from that rule, so CON can be open for both reading and writing, but a device opened with MODE_DENY_RW can’t be open anywhere else (see Device Sharing).

A filename that is only a drive letter and colon (eg, C:) opens the entire volume, whose sectors can then be read (or written) at file offsets of LBA * bytes per sector; the size of the file is the size of the volume. For sharing purposes, a volume counts as every file on it: it can be opened for reading only if no file on it is open for writing, and for writing only if no file on it is open at all, and while the volume is open, no file on it can be opened in a way that conflicts with that. Creating, deleting, or renaming a file, and creating or removing a directory, also fail with ERR_SHARE while the volume is open. Opening a volume writes any modified buffers for the drive, writing to it discards the drive’s buffers, and closing a volume that was written rebuilds its BPB (eg, after it’s been reformatted). Creating a volume (3Ch, which is how OPEN FOR OUTPUT opens it) simply opens it for writing. A volume whose media is unknown (eg, an unformatted diskette) can still be opened: the media check is done with hard errors treated as FAIL (so there’s no critical error prompt), and only an invalid drive is an error; the volume’s size is then zero (its size is refreshed from its BPB at every read and write) until the drive’s driver is given valid parameters (see IOCTL_SETPARMS in IOCTL Functions), which is how FORMAT.BAS formats a new diskette.

For IOCTL code 00h (IOCTL_GETDATA), DOS returns DX = 80h for a device, or the file’s drive # (0-based) for a file. All other IOCTL codes are passed to the device driver as a DDC_IOCTLIN request (for a volume handle, to the drive’s block driver, with the drive # as the unit, and IOCTL errors are returned to the caller rather than reported as critical errors); see IOCTL Functions for the BASIC-DOS-specific codes.

File Control Blocks

Any FCB function can be passed an extended FCB (an FCB preceded by 7 bytes, the first of which is FFh and the last of which contains search attributes, or the attributes of a file being created). FCB functions always use the drive’s current directory, and FCB names that are device names (eg, NUL or CON) open the device.

An FCB opens a file read-only, so any number of FCBs (and handles opened for reading) can open the same file; the FCB’s first write (or truncation) upgrades it to read-write, which fails (AL = 1) if the file is read-only or already open for writing elsewhere. Deleting or renaming with wildcards skips files that are read-only, directories, volume labels, or open. Searches (11h and 12h) keep their position in the FCB’s FCB_CURBLK field, so the same FCB must be used to continue a search.

Memory

Processes

Miscellaneous

The path character is set at boot by CONFIG.SYS’s PATHCHAR setting (\ by default, or /), which also determines the default switch character: /, or - with PATHCHAR=/. CONFIG.SYS’s SWITCHAR setting (- or /), or a - boot key, can also change the switch character, but never to the path character, so the two are never the same. Both are fixed at boot; unlike PC DOS, BASIC-DOS doesn’t support AX = 3701h (set switch character), so CONFIG.SYS (or the boot key) is the only way to change them. | 52h | DOS_MSC_GETVARS | | ES:BX -> DOSVARS |

Differences from PC DOS

DOS_MSC_GETVER

Returns the BASIC-DOS version, which is currently 2.00, so that PC DOS 2.x programs pass their version checks:

• AL = major version
• AH = minor version
• BX = 4442h (“BD” in memory; SIG_BASICDOS in dosapi.inc), which identifies BASIC-DOS, since a PC DOS 2.x BX holds an OEM number and serial number instead
• CX = internal state (bit 0 is set in DEBUG builds)

A program that demands one exact version, by following the INT 21h with XCHG AH,AL and CMP AX,imm16 (as EXE2BIN 3.20 does, comparing with 0314h), gets that version instead: when the byte at the caller’s CS:IP+2 is 3Dh, AX returns the word that follows it, byte-swapped.

Memory Allocation

DOS_MEM_ALLOC takes a block type in AL, which is stored in the block’s MCB (MCB_TYPE). Types include MCBTYPE_NONE (0) and the types COMMAND.COM uses for its own blocks (‘C’ code, ‘F’ function, ‘V’ variable, ‘S’ string, ‘T’ text, and ‘A’ array). Setting bit 7 of AL (MCBTYPE_HIGH) allocates the block from the top of the last free block that’s large enough, rather than the bottom of the first, so that long-lived blocks don’t fragment the memory below them.

Programs aren’t given all available memory when they’re loaded (see Memory Layout), so a program doesn’t need to shrink its memory before allocating more.

Program Loading

DOS_PSP_EXEC1 (4B01h) is the undocumented PC DOS function that debuggers use to load a program without starting it. BASIC-DOS adds DOS_PSP_EXEC2 (4B02h), which starts a program loaded by DOS_PSP_EXEC1; the current PSP must still be the new program’s PSP. BASIC-DOS also adds DOS_PSP_EXEC6 (4B06h), which is DOS_PSP_EXEC1 for a caller that will load more programs next, with CH = the number of those programs (COMMAND.COM passes the number of commands that follow in a pipeline). Only DOS_PSP_EXEC6 reads CH, so older programs, which never use subfunction 6, never request a reservation by accident.

An EXE file’s maximum allocation (usually FFFFh, “all the memory”) is honored, as in PC DOS, but only up to a fair share of the free memory: 1/N, where N is one plus the number of other sessions that have loaded a program, plus the number of programs the caller said it will load next. A program never gets less than its minimum allocation, if that much is available. So a program that needs nearly all of memory (eg, WOLF3D.EXE) gets it when the other sessions are idle, two sessions each running a program split the memory, and the stages of a pipeline each get a share.

BASIC-DOS also stores additional information in the PSP, in fields that PC DOS leaves unused (see PSP): the session number (PSP_SCB), the program’s initial stack and start address, its heap, its exit code and exit type, and command-line switches parsed by DOS_UTL_PARSESW.

Environments aren’t copied: a new program’s PSP_ENVSEG is simply EPB_ENVSEG, or if that’s zero, its parent’s environment (which is safe to share, since the parent outlives the program). COMMAND.COM gives every program it runs an environment containing COMSPEC (the path of COMMAND.COM) and PATH (the current PATH$), mainly for older programs (eg, MAKE) that use them to find and run other programs; and when COMMAND.COM itself is given an environment containing PATH, it sets PATH$ from it.

For the same reason, COMMAND.COM supports COMMAND /C command, which is how the C runtime’s system() function runs a command: the command is run, and then COMMAND.COM exits, with ERRORLEVEL as its exit code. Unlike PC DOS, whose COMMAND /C always returns 0, this lets a program like MAKE stop when a command fails. Without /C, any commands following COMMAND are run as startup commands (see COMMAND), and COMMAND.COM keeps running.

Files

Any filename passed to a handle function (or to FFIRST, DELETE, RENAME, MKDIR, RMDIR, CHDIR, or EXEC) may include a path, whose directory names are separated by the session’s path character (DOS_MSC_GETPCH), not by both \ and / as in PC DOS. FCB functions always use the drive’s current directory. A subdirectory grows by a cluster whenever a new entry doesn’t fit. Same-drive renames can move files and directories without copying their data; existing destinations and open source files are rejected. Directory moves update the “..” entry and reject destinations within the moved subtree. Current directories and open child files remain valid because their directory cluster identities are unchanged. Cross-drive moves are not supported. A read-only file can’t be opened for writing (3Dh with MODE_ACC_WO or MODE_ACC_RW), replaced (3Ch), or deleted (41h); each fails with ERR_ACCDENIED, as does writing to a read-only file through an FCB. As in PC DOS, a file that 3Ch creates with the read-only attribute is writable through the handle that 3Ch returns. INT 25h and INT 26h aren’t supported, and won’t be; for absolute disk reads and writes, open the volume as a file instead (see File Handles). Block device errors are reported to the session’s critical error handler (see Critical Errors).

BASIC-DOS doesn’t store the path of each current directory, only the directory’s first cluster (in a table with one entry per drive for each session), so DOS_DSK_GETCWD rebuilds the path by following “..” entries up to the root.

Sessions

Each session has its own current drive, current directory for every drive, DTA, switch and path characters, CTRL-C state, and exit, CTRL-C, and critical error handlers, all of which are stored in its SCB. For example, DOS_MSC_SETVEC with vector 23h changes only the current session’s CTRL-C handler.

Critical Errors

When a block device request fails (eg, a diskette drive isn’t ready, or a diskette is write-protected), DOS calls the session’s critical error handler (INT 24h) with the same inputs as PC DOS:

The handler returns its response in AL: 0 (CRERR_IGNORE) to treat the request as completed, 1 (CRERR_RETRY) to reissue it (the driver resumes at the failing sector), 2 (CRERR_ABORT) to terminate the program, or 3 (CRERR_FAIL) to fail the DOS function with the error code in Error Codes (19-31). IGNORE is allowed only for read and write requests (eg, not when the drive’s BPB can’t be built); if the handler returns IGNORE when it isn’t allowed, or any other unrecognized response, the request fails. ABORT ends the program with exit type EXTYPE_ERROR and exit code 255 (0FFh) as soon as the DOS function returns, so DOS unwinds normally first; if the program is a session’s shell, which can’t be terminated, ABORT behaves like CTRL-C (without the echo).

The handler is called on a DOS stack (ERR_STACK_SIZE, 512 bytes, in dos.inc), since the stack of the program that called DOS may have little room to spare, and with the session locked, so no other session runs until the handler returns; a critical error inside the handler itself fails immediately. As in PC DOS, a handler should limit itself to console functions (01h-0Ch) and must not call functions that use the disk; a CTRL-C typed while the handler is running ends the handler with an ABORT response.

The default handler displays the traditional message and prompt on the session’s console and reads the response (A, R, I, or F; CTRL-C is ABORT); for example:

Not ready error reading drive B
Abort, Retry, Fail? 

“Ignore, “ appears only when IGNORE is allowed. A session whose input isn’t its console (eg, a command after the first in a pipeline) gets the message but no prompt, and its response is FAIL. Programs install their own handler with DOS_MSC_SETVEC (vector 24h), which affects only the current session (see Sessions); DOS restores the previous handler when the program ends.

Exit Types

DOS_PSP_RETCODE returns one of these exit types in AH:

When DOS_PSP_RETCODE reports EXTYPE_CTRLC, BASIC-DOS also signals CTRL-C to the caller (without echoing it again), so a CTRL-C ripples up through every parent whose CTRL-C handler terminates it (eg, from MASM to MAKE to COMMAND, which then abandons any BAT or BAS files that were running and returns to its prompt). The exit type is reset to EXTYPE_NORMAL first, so if the caller’s handler restarts the call, it returns the exit code with EXTYPE_NORMAL.

However a program terminates, any of vectors 01h, 03h, 08h, 09h, 1Bh, and 1Ch that still points into its memory is restored to the value it had when BASIC-DOS started, since some programs (eg, DEBUG and MSBASIC) hook those vectors directly and restore them only when they exit normally.

Error Codes

« ArchitectureUtility Functions »