BASIC-DOS provides a set of utility functions through INT 2Bh, with the function number in AH. The DOS_UTL_* names are defined in dosapi.inc (define DOSFUNC before including it), and the DOSUTIL macro (in macros.inc) generates the calls:
DOSUTIL STRLEN ; MOV AH,DOS_UTL_STRLEN / INT 2Bh
Utility functions differ from DOS functions in a few ways, because some of them are called from interrupt handlers:
At ring 3, DOS_UTL_HPRINTF, DOS_UTL_WAIT, DOS_UTL_ENDWAIT, DOS_UTL_HOTKEY, DOS_UTL_LOCK, and DOS_UTL_UNLOCK return ERR_ACCDENIED (see Running Programs at Ring 3).
Device drivers can also call DOS_UTL_WAIT, DOS_UTL_ENDWAIT, DOS_UTL_HOTKEY, DOS_UTL_LOCK, and DOS_UTL_UNLOCK with a far call to DDINT_UTIL (0050:0049h), with AH set to the function number, which avoids the stack overhead of an INT 2Bh call.
| AH | Name | Description |
|---|---|---|
| 00h | DOS_UTL_STRLEN | Returns the length of a null-terminated string |
| 01h | DOS_UTL_STRSTR | Finds a string within another string |
| 02h | DOS_UTL_STRUPR | Converts a string to upper case |
| 03h | DOS_UTL_PRINTF | printf to the console (STDOUT) |
| 04h | DOS_UTL_HPRINTF | printf to a system file handle |
| 05h | DOS_UTL_DPRINTF | printf to the DEBUG$ device, if any |
| 06h | DOS_UTL_SPRINTF | sprintf to a buffer |
| 07h | DOS_UTL_TPRINTF | printf to the console with typed parameters (used by PRINTF USING) |
| 08h | DOS_UTL_ITOA | Converts a 32-bit number to a string |
| 09h | DOS_UTL_ATOI16 | Converts a string to a validated 16-bit number |
| 0Ah | DOS_UTL_ATOI32 | Converts a string to a 32-bit number |
| 0Bh | DOS_UTL_ATOI32D | Converts a decimal string to a 32-bit number |
| 0Ch | DOS_UTL_TOKEN1 | Splits a string into whitespace-separated tokens |
| 0Dh | DOS_UTL_TOKEN2 | Splits a string into BASIC tokens |
| 0Eh | DOS_UTL_TOKID | Looks up a token in a sorted token table |
| 0Fh | DOS_UTL_PARSESW | Parses command-line switches |
| 10h | DOS_UTL_GETDEV | Returns the driver header for a device name |
| 11h | DOS_UTL_GETCSN | Returns the current session number |
| 12h | DOS_UTL_QRYSCB | Returns information about a session |
| 13h | DOS_UTL_LOAD | Loads a program into a new session |
| 14h | DOS_UTL_START | Starts a session |
| 15h | DOS_UTL_STOP | Stops a session (not implemented yet) |
| 16h | DOS_UTL_END | Ends the current program in a session |
| 17h | DOS_UTL_WAITEND | Waits for all programs in a session to end |
| 18h | DOS_UTL_YIELD | Lets another session run |
| 19h | DOS_UTL_SLEEP | Sleeps for a number of milliseconds |
| 1Ah | DOS_UTL_WAIT | Waits on an ID |
| 1Bh | DOS_UTL_ENDWAIT | Ends a wait on an ID |
| 1Ch | DOS_UTL_HOTKEY | Notifies DOS of a hotkey (used by the console drivers) |
| 1Dh | DOS_UTL_LOCK | Locks the current session (disables session switches) |
| 1Eh | DOS_UTL_UNLOCK | Unlocks the current session |
| 1Fh | DOS_UTL_QRYMEM | Returns information about a memory block |
| 20h | DOS_UTL_TERM | Terminates the program with an exit code and type |
| 21h | DOS_UTL_RESTART | Restarts the system |
| 22h | DOS_UTL_GETDATE | Returns the date, including a packed date |
| 23h | DOS_UTL_GETTIME | Returns the time, including a packed time |
| 24h | DOS_UTL_INCDATE | Advances a date by one day |
| 25h | DOS_UTL_EDITLN | Reads an edited line of console input |
| 26h | DOS_UTL_SOUND | Plays a sound for a number of clock ticks |
| 27h | DOS_UTL_ALIAS | Returns a code segment for a memory block, or the reverse |
| 28h | DOS_UTL_MAPSEG | Returns a selector for a real-mode segment, or a word below 1Mb |
DOS_UTL_STRLEN (00h): DS:SI -> null-terminated string. Returns AX = length.
DOS_UTL_STRSTR (01h): CS:SI -> null-terminated string to find (in the caller’s code segment), ES:DI -> null-terminated string to search. On a match, carry is clear and DI is updated to the position of the match; otherwise, carry is set.
DOS_UTL_STRUPR (02h): DS:SI -> string, CX = length (0 if null-terminated). Converts the string to upper case.
DOS_UTL_PRINTF (03h) prints to STDOUT, using a format string stored in the code segment immediately after the INT 2Bh instruction (DOS skips over it when returning). All other parameters are pushed on the stack from right to left, and removed by the caller after the call (eg, with ADD SP,N*2). Returns AX = # of characters printed. The PRINTF macro takes care of all of this:
PRINTF <"%d files, %ld bytes",13,10>,cx,ax,dx
DOS_UTL_HPRINTF (04h) is the same, but prints to the system file handle (SFH) in BL.
DOS_UTL_DPRINTF (05h) is the same, but prints to the DEBUG$ device (the port of the DEBUG.COM driver), if it’s installed, and only in a DEBUG build of BASDOS.COM (otherwise, the format string is skipped). The DPRINTF macro generates these calls, in DEBUG builds only.
DOS_UTL_SPRINTF (06h): like DOS_UTL_PRINTF, its format string follows the INT 2Bh instruction (DOS returns after it), but DS:BX must point to it, too; ES:DI -> output buffer, CX = buffer length, and parameters pushed as above. Returns AX = # of characters generated.
DOS_UTL_TPRINTF (07h): DS:BX -> format string, with “typed” parameters pushed right to left: each is a type word (VAR_LONG, VAR_STR, or VAR_DOUBLE; see parser.inc) followed by a 4-byte value, so a specifier’s size modifiers are ignored. Numeric and date/time specifiers take a VAR_LONG, %s takes a VAR_STR (a far pointer to a length-prefixed string, or null if empty), %f takes a VAR_DOUBLE (a far pointer), and %c takes a VAR_LONG or the first character of a VAR_STR; a value of any other type prints the specifier unchanged. Prints to STDOUT and returns AX = # of characters printed. COMMAND’s PRINTF USING uses this.
Supported format specifiers include:
| Specifier | Parameter |
|---|---|
%c |
8-bit character |
%d, %bd, %ld |
Signed 16-bit, 8-bit, or 32-bit decimal integer |
%u, %bu, %lu |
Unsigned 16-bit, 8-bit, or 32-bit decimal integer |
%x, %bx, %lx |
Unsigned 16-bit, 8-bit, or 32-bit hexadecimal integer |
%s, %ls |
String (near DS-relative pointer, or far pointer) |
%f |
Double, formatted by the FPU$ driver; the parameter is a far pointer to the double |
%W, %F, %M, %D, %X, %Y |
Day of week, month name, month, day, 2-digit year, and 4-digit year of a packed date |
%G, %H, %N, %S, %A |
12-hour hour, 24-hour hour, minute, second, and a or p of a packed time |
%n |
A new line: a carriage return and line feed (no parameter) |
%% |
A percent sign (no parameter) |
Specifiers also support the # and - flags, a width, and a precision (eg, %-10.4s). 32-bit values are passed as two 16-bit parameters, low word first (as in the PRINTF example above, where AX is the low word of %ld).
DOS_UTL_ITOA (08h): DX:SI = value, BL = base, BH = flags (PF_*, eg, PF_HASH to print a space instead of a minus sign for non-negative values), CX = minimum length (0 for none), ES:DI -> buffer. Returns AL = # of digits, and DI advanced.
DOS_UTL_ATOI16 (09h): DS:SI -> string, BL = base, ES:DI -> validation triplet of 16-bit (default, minimum, maximum) values, or DI = -1 for no validation. Returns AX = value, with SI advanced past the first non-digit and DI advanced to the next triplet, making it easy to parse a series of values; carry is set on a validation error (and AX is the default value).
DOS_UTL_ATOI32 (0Ah): DS:SI -> string, CX = length (-1 if unknown), BL = base. Returns DX:AX = value, with SI pointing to the first unprocessed character; carry is set if there were no digits.
DOS_UTL_ATOI32D (0Bh): Same as DOS_UTL_ATOI32 with BL = 10 and CX = -1, without using BX or CX.
DOS_UTL_TOKEN1 (0Ch) and DOS_UTL_TOKEN2 (0Dh): CL = string length, DS:SI -> string, ES:DI -> token buffer (TOKBUF; see parser.inc). TOKEN1 returns only tokens separated by whitespace (or the switch character), while TOKEN2 parses BASIC syntax and returns all tokens, including whitespace. For TOKEN2, a type suffix (%, $, !, or #) is part of a name’s token, except that a # followed by a digit starts a new token, since it begins a file number (eg, PRINT#1 is PRINT, #, 1). Returns carry clear and AX = # of tokens if any were found.
DOS_UTL_TOKID (0Eh): CX = token length, DS:SI -> token, CS:DX -> token table (TOKTBL, followed by TOKDEFs sorted by name). Returns carry clear, AX = token ID, and SI -> the TOKDEF if found; otherwise, carry set and AX = 0.
DOS_UTL_PARSESW (0Fh): DL = first token to parse, DH = # of non-switch tokens to ignore, ES:DI -> TOKBUF. Sets a bit in PSP_DIGITS or PSP_LETTERS (see PSP) for each switch character found (eg, /P sets the bit for P), stopping at the end of the command (a symbol, eg, a pipe), and returns DL = first non-switch token. Any character other than 0 through ? or a letter (eg, the dots in /..), or a switch character with nothing after it, sets the bit for ?.
DOS_UTL_GETDEV (10h): DS:DX -> device name. Returns ES:DI -> device driver header, or carry set if not found. For CON, AUX, or PRN, it’s the driver of the session’s device (carry set if the session has no such device).
DOS_UTL_GETCSN (11h): Returns CL = current session number.
DOS_UTL_LOAD (13h): ES:BX -> Session Parameter Block (see SPB), which specifies the command line and the standard handles for the new session, CH = the number of programs the caller will load next (eg, the rest of a pipeline), which the loader sets aside memory for (see DOS_PSP_EXEC1), and AL = 0 for a session that shares the caller’s LDT (eg, a pipeline’s next program), or 1 for a session with an LDT of its own (eg, for START; see LDTs). Loads the program into an available session; returns CL = session number, or carry set and AX = error code.
DOS_UTL_START (14h): CL = session number. Marks the session startable; it starts running at the next session switch.
DOS_UTL_STOP (15h): CL = session number. Not implemented yet.
DOS_UTL_END (16h): CL = session number, AL = 0 to end the session’s current program, or 1 to end the session. AL = 0 aborts the current program (as CTRL-ALT-DEL does); the program can’t intercept the abort, which takes effect the next time the session leaves DOS (a session waiting on a pipe or device is interrupted first). Use DOS_UTL_WAITEND to wait for the session to end. Carry is set (AX = ERR_BADSESSION) if the session number is invalid or the session isn’t running a program. AL = 1 aborts each of the session’s programs in turn, including its last one, which an abort otherwise returns to its prompt (see CTRL-ALT-DEL), and then closes the session; if no other session is left, the system halts. The exception is the shell of a session that sysinit loaded (PSP_SHELL): the aborts stop there, and the shell returns to its prompt, so the session stays open. COMMAND.COM uses AL = 0 to end the other commands of a pipeline when one of them fails, and AL = 1 for KILL session.
DOS_UTL_WAITEND (17h): CL = session number. Waits for all programs in the session to end.
DOS_UTL_QRYSCB (12h): CL = session number, ES:DI -> 8-byte buffer. Returns AX = the PSP of the session’s program (zero if none), SI:DX = the memory the session is using (in bytes): every block owned by its program, and by that program’s parent, and so on (eg, a COMMAND.COM and the program it’s running), plus any shared code block that one of them is the first to share (so that the code that copies of COMMAND.COM share at ring 3 is counted once, in one session), and fills the buffer with the name (8 characters) of the session’s program, all zeros if there isn’t one (eg, a session that has never been used) or it can’t be found; or carry set if the session number is invalid. The name is copied, rather than returned as a pointer, since a program at ring 3 can’t read the kernel’s memory, and a caller can’t find it through the PSP: in protected mode, PSP-1 isn’t an MCB, and the PSP may be a selector in another session’s LDT, so DOS finds the program’s blocks by its owner ID instead. COMMAND.COM uses this for START’s session list, so that it doesn’t depend on the kernel’s internal session structures.
DOS_UTL_YIELD (18h): Lets another session run, if one is ready.
DOS_UTL_SLEEP (19h): CX:DX = # of milliseconds to sleep.
DOS_UTL_WAIT (1Ah): DX:DI = wait ID (typically the address of a request packet). Marks the current session as waiting until another caller (typically a driver’s interrupt handler) calls DOS_UTL_ENDWAIT with the same ID. Carry is set if the wait was interrupted (eg, by CTRL-C or CTRL-ALT-DEL), in which case the caller must clean up whatever it was waiting on.
DOS_UTL_ENDWAIT (1Bh): DX:DI = wait ID. Makes any session waiting on the ID runnable again; carry is set if no session was waiting.
DOS_UTL_HOTKEY (1Ch): CX = console context, DL = character code, DH = scan code. Used by the console drivers (VKD$ and COM) to notify DOS of CTRL-C, CTRL-P, and CTRL-ALT-DEL; a CTRL-C is also left in the driver’s input, for DOS to discard (see Device Drivers).
DOS_UTL_LOCK (1Dh): Locks the current session, so that no session switch occurs until DOS_UTL_UNLOCK is called. Returns AX = the console context of the current session (0 if none).
DOS_UTL_UNLOCK (1Eh): Unlocks the current session, performing any session switch that was deferred while it was locked.
DOS_UTL_QRYMEM (1Fh): Returns information about a memory block (anywhere in memory, conventional or extended), as the CPU$ driver describes it (see CPU_QUERY).
Inputs:
Outputs (carry clear if a block was found; carry set if there are no more blocks of the requested type):
The MEM command uses this function to total the free memory blocks.
Free memory is also useful for data that can be recreated if it’s overwritten. For example, while a program runs, COMMAND.COM keeps a copy of its transient portion in a block that it allocates at the top of free memory (DOS_MEM_ALLOC with MCBTYPE_HIGH) and then frees. When the program ends, it allocates the same size there again, which is the same memory unless something else has allocated it in the meantime, and checks the copy’s checksum. It can’t simply keep the freed block’s segment, since in protected mode a freed block’s selector isn’t valid. Since the block is free while the program runs, another session can allocate it at any time, so a caller should use DOS_UTL_LOCK and DOS_UTL_UNLOCK around any code that writes to the block or relies on its contents (eg, from the first allocation through the copy, and from the second allocation through copying it back).
DOS_UTL_ALIAS (27h): AL = 0, BX = segment (or selector) of a memory block. Returns AX = a code segment (or selector) for the same memory, so that a program can run code that it writes into the block (eg, COMMAND.COM’s compiled BASIC code). In real mode, it’s the block’s own segment; in protected mode, it’s the block’s code alias (see CPU_ALIAS), which CPU$ creates the first time it’s requested and frees with the block, so it’s no longer valid once the block is freed. Carry is set if there’s no selector for it (AX = error code). With AL = 1, BX = a block’s code alias (eg, a program’s CS), and it returns the block’s own segment (or selector, with the alias’s RPL) in AX, so that a program can change code that it runs through the alias (eg, DEBUG.COM storing a breakpoint at ring 3, where code selectors aren’t writable); in real mode, it’s BX itself. Carry is set if BX isn’t the start of a block (AX = error code).
DOS_UTL_MAPSEG (28h): AL = 0, BX = real-mode segment. Returns AX = a segment (or selector) for that segment’s 64K, for programs that read and write memory by segment (eg, BASIC’s DEF SEG, PEEK, and POKE). In real mode, it’s the segment itself. In protected mode, it’s a selector that the session keeps until its next DOS_UTL_MAPSEG call (which frees it, and like DOS_MEM_FREE, returns 0 in ES or DS if either held it): writable for video memory (segments A000h through BFFFh), and read-only everywhere else, so that a program can read low memory (eg, the BIOS data area) and the ROMs, but not change them. Carry is set if there’s no selector for it (AX = error code). With AL = 1 (in protected mode only), BX:SI = a physical address below 1Mb, and it returns the word there in AX, without using or replacing the session’s selector, which may belong to another program in the session (eg, for its parent’s DEF SEG); a debugger uses this to read memory that its own selectors can’t reach. Carry is set if the address isn’t below 1Mb (AX = error code).
DOS_UTL_TERM (20h): DL = exit code, DH = exit type (see Exit Types). Terminates the current program.
DOS_UTL_RESTART (21h): Writes any modified disk buffers, sets the ROM BIOS reset flag at 40:72h to 1234h, so that the ROM performs a warm boot (skipping its memory tests), and restarts the system.
DOS_UTL_GETDATE (22h): Same outputs as DOS_MSC_GETDATE (CX = year, DH = month, DL = day, AL = day of week), plus AX = packed date: bits 15-9 = year - 1980, bits 8-5 = month, bits 4-0 = day. Carry is unchanged.
DOS_UTL_GETTIME (23h): AL = 0. Same outputs as DOS_MSC_GETTIME (CH = hours, CL = minutes, DH = seconds, DL = hundredths), plus AX = packed time: bits 15-11 = hours, bits 10-5 = minutes, bits 4-0 = seconds / 2. Carry is unchanged. With AL = 1, it returns the ROM BIOS tick count (about 18.2 ticks per second, since midnight) in DX:AX instead, which a program at ring 3 can’t read from the BIOS data area itself (COMMAND.COM uses it for RANDOMIZE TIMER, SOUND, and PLAY).
DOS_UTL_INCDATE (24h): CX = year, DH = month, DL = day. Returns the date advanced by one day.
DOS_UTL_EDITLN (25h): DS:DX -> input buffer, as for DOS_TTY_INPUT, and AL = options: bit 0 returns AX = the last editing action, so that the caller can respond to keys like Up and Down (eg, for command history), and bit 1 displays the buffer’s existing characters (INP_CNT) first, as if they had been recalled, so that they can be edited (COMMAND.COM uses this for AUTO and EDIT). Otherwise, it’s the same as DOS_TTY_INPUT.
DOS_UTL_SOUND (26h): CX = # of clock ticks, DX = PIT divisor for the frequency (1193182 / frequency), or 0 to turn the sound off. Starts the sound and returns immediately; the CLOCK$ driver turns the sound off after the specified number of ticks.
Copyright (c) 2020-2026 Jeff Parsons Released under MIT License