BASIC-DOS

A PCjs Retro-Programming Project

Project maintained by jeffpar

BASIC-DOS Manual

BASIC-DOS Screen Commands

Screen commands include:

A console may occupy only part of the screen (see Sessions). Screen commands operate on the current session’s console, and coordinates are relative to the console, not the screen.

When a BAS program that used a graphics mode ends (or is aborted), the video mode it started with is restored, along with the console’s original size and border, even if the program returned to a text mode first (eg, DONKEY.BAS, whose SCREEN 0 leaves 40 columns); otherwise, text-mode changes (eg, WIDTH 40 or SCREEN 0,0) persist, as in Microsoft BASIC.

CLS

CLS

Clears the console using the background color and moves the cursor to the top left corner. After VIEW PRINT, only the scrolling rows are cleared, and the cursor moves to the first one. Outside a BAS program (eg, at the prompt), CLS also restores a console’s border, if WIDTH or MODE removed it (eg, MODE 40 in a 40-column console).

COLOR

COLOR [foreground][,[background][,border]]

Sets the foreground (0-15), background (0-7), and border (0-255) colors of the console. For blinking colors, use 16-31 for foreground and 128-255 for border; as in MSBASIC, a background of 8-15 is the same as 0-7 (it doesn’t make the foreground blink). Omitted values are unchanged (eg, COLOR ,1).

In SCREEN 1, the values are the background color (0-15) and palette (0 or 1) instead.

The colors are:

0 Black 4 Red 8 Gray 12 Light Red
1 Blue 5 Magenta 9 Light Blue 13 Light Magenta
2 Green 6 Brown 10 Light Green 14 Yellow
3 Cyan 7 White 11 Light Cyan 15 Bright White

A VT100 terminal (see CON) has no colors, so it displays the attributes that a monochrome adapter displays for them instead: COLOR 0,7 is reverse video, a foreground of 1 is underlined, 8-15 are bold, and 16-31 blink (eg, COLOR 9 is bold and underlined, and COLOR 7,0 is normal again). A VT100 without the Advanced Video Option has only one of reverse video and underline (whichever its SET-UP cursor selects), which both settings display, and neither bold nor blink. Other ANSI terminals are sent the colors, plus bold and blink.

ECHO

ECHO [ON|OFF]

Controls the echo of lines in a BAT file. After ECHO ON, a BAT file echoes each line before running it, until ECHO OFF is used; a line beginning with @ is never echoed (eg, @ECHO ON). Echoed lines are displayed with a @ in front (eg, @REM Starting), where PC DOS would display a prompt, but without the blank line that PC DOS displays before each prompt. ECHO without ON or OFF displays the current setting.

Every BAT file run from the prompt (or by a startup command) starts with ECHO OFF, unlike PC DOS, so BAT files behave like BAS files unless ECHO ON is used; the setting remains in effect when one BAT file runs another. BAS files never echo their lines. A @ at the start of a command typed at the prompt is ignored, as in later versions of PC DOS.

LOCATE

LOCATE [row][,[col][,cursor]]

Moves the cursor to the specified row and col (starting at 1,1), and hides (0) or shows (1) the cursor. Omitted values are unchanged.

As in MSBASIC, the cursor is hidden while a BAS program runs, but only once the program uses the screen (SCREEN, WIDTH, CLS, or LOCATE with a row, col, or a cursor of 0), so that programs that only print, such as the BAS utilities (eg, CHKDSK), leave the cursor visible, like any other program. Once hidden, the cursor is shown during keyboard input (eg, INPUT) and while an external program that the BAS program starts is running, and then hidden again, until the program ends. A cursor shown with LOCATE ,,1 stays visible until the next input ends. Statements typed at the prompt and BAT files leave the cursor alone, where a cursor hidden with LOCATE ,,0 remains hidden until the next input.

On a serial console, a terminal is assumed to have 24 rows and 80 columns, its cursor is always visible, and the current row (see CSRLIN) is the row that BASIC-DOS has calculated from everything written since the console started, so it’s correct once the screen has been cleared (or has scrolled) and only until a program sends the terminal an escape sequence of its own. A GENERIC terminal can’t move its cursor, so LOCATE is an “Illegal function call” there.

So that programs written for a 25-row screen still run on a 24-row terminal, LOCATE also accepts row 25 there: the cursor waits on row 24, and whatever is printed is ignored until the next LOCATE (or until a line ends, which continues on row 24).

PRINT

PRINT [#n,][expression][separator][expression]…

Prints a series of values. Each separator is a semicolon, which prints the next value immediately after the previous one, or a comma, which prints a tab; a space or tab between values works like a semicolon. Numbers are printed with a leading space (or minus sign) and a trailing space. If the list ends with a semicolon or comma, the cursor remains on the same line; otherwise, PRINT moves to the next line.

With #n, PRINT writes the same output to file n, which must be open for OUTPUT or APPEND, or be a device opened without FOR (see OPEN). As in Microsoft BASIC, the space before the # is optional (eg, PRINT#1,X). The # form isn’t available on low memory systems.

PRINT "A"; 1; "B", 2
A 1 B	 2

On the PC’s display, as in PC DOS, control characters other than BELL (7, which beeps), BACKSPACE (8), TAB (9), LINEFEED (10), and RETURN (13) are displayed as the PC’s graphic characters (eg, PRINT CHR$(14) displays a musical note); unlike IBM PC BASIC, characters such as CHR$(12) and CHR$(28)-CHR$(31) don’t clear the screen or move the cursor. On a serial console, they’re sent to the terminal as they are.

PRINTF

PRINTF [#n,]USING format;[value][separator][value]…

Prints the values using the C-style specifiers in format, as a simpler alternative to the PRINT USING of other BASICs. Each % specifier takes the next value: %d or %u prints a number (%x in hexadecimal, and %#d with a leading space for positive numbers, like PRINT), %f prints a double (BASIC-style unless a precision is given), %s prints a string, and %c prints a character (from a number or the first character of a string). Specifiers accept the - flag (left-justify), a width, and a precision (eg, %5d, %-8.3s, %.2f), and %% prints a percent sign. Other specifiers print part of a number that holds a packed DOS date or time (eg, from a DIR$ entry): %M, %D, and %Y print a date’s month, day, and year (%X prints the year with 2 digits), %F and %W print the names of its month and day of the week (eg, %.3F prints Oct), and %H, %N, and %S print a time’s hour, minute, and second (%G prints a 12-hour hour, and %A prints a or p). %n takes no value; it starts a new line (a carriage return and line feed). Since the values carry their own types, size modifiers like l are unnecessary, and a value of the wrong type prints its specifier unchanged. Each separator is a semicolon, comma, space, or tab (only format determines what’s printed), and as with PRINT, the cursor moves to the next line unless the list ends with a semicolon or comma. With #n, PRINTF writes the same output to file n, which must be open for OUTPUT or APPEND.

PRINTF USING "%-6s|%5d|%.2f"; "abc", 42, 3.14159
abc   |   42|3.14

Comma print zones aren’t supported yet (commas currently print a tab). PRINT USING isn’t supported, and won’t be, since PRINTF USING covers the same needs (see below).

How to replace PRINT USING

The PRINT USING (and LPRINT USING) statement of other BASICs formats values with templates, such as "###.##". To convert one to PRINTF USING, replace each field of the template with the corresponding specifier:

PRINT USING PRINTF USING Notes
! %.1s or %c The first character of a string
\ \ %-4.4s The first n characters of a string (here, 4), padded with spaces to n
& %s The entire string
### %3d or %3.0f A number, right-justified in a field as wide as the #s; %d for an integer, %f for a double
###.## %6.2f A double, with as many decimal places as #s after the point (the width includes the point)
+### or ###- None PRINTF has no + flag; %#d prints a space before a positive integer, as PRINT does
**###.## None PRINTF can’t fill with asterisks; %06.2f fills with zeros instead
$$###.## $%.2f A dollar sign right before the number (but without a fixed width); $%7.2f puts it at the start of the field instead
#,###.## None PRINTF doesn’t insert thousands separators
##.##^^^^ %f PRINTF has no exponential format, but %f without a precision prints very large or small numbers in exponential form (eg, 1E+20), as PRINT does
_ Omit it _ prints the next character literally, which PRINTF does anyway (except %, which must be %%)
Other characters Same Literal text

The other differences to watch for:

  • Repeating fields: PRINT USING reuses its template for each value, but PRINTF USING uses each specifier once (and ignores extra values), so repeat the specifiers instead (eg, PRINT USING "###";A;B;C becomes PRINTF USING "%3d%3d%3d";A;B;C).
  • Types: %d requires an integer and %f requires a double, and a value of the wrong type prints its specifier as-is. Variables without a suffix are doubles in BAS files but integers in BAT files, and constants without a decimal point or exponent (eg, 42) are integers (see Variables and Types), so use CINT or CDBL to convert a value when necessary (eg, PRINTF USING "%3d";CINT(I)).
  • Overflow: when a number doesn’t fit in its field, PRINT USING prints a % before it, but PRINTF simply widens the field.
  • Rounding: PRINTF rounds a number that’s exactly halfway to the nearest even digit (eg, %.0f prints 2.5 as 2), whereas PRINT USING rounds it up.

For example, the MORTGAGE.BAS sample (one of the PC DOS 1.00 BASIC samples, in the hard disk’s TESTS\SAMPLES directory) printed its amortization table with:

2730 PRINT USING "### ";I;
2740 PRINT USING "  ######.##";PF-AMORT(I,2);AMORT(I,2);AMORT(I,1)

and now prints it with:

2730 PRINTF USING "%3.0f ";I;
2740 PRINTF USING "  %9.2f  %9.2f  %9.2f";PF-AMORT(I,2);AMORT(I,2);AMORT(I,1)

LPRINT

LPRINT [expression][separator][expression]…

Prints like PRINT, but to the printer (PRN, which is the first parallel port, LPT1, unless PRN= in CONFIG.SYS chooses another device). If there’s no PRN device (eg, the machine has no parallel port), a “Device unavailable” error occurs after the statement, and a printer can report “Device timeout” (eg, if it’s offline), “Out of paper”, or “Device fault”; PRINT # to a printer (eg, a file opened as “PRN” or “LPT2”) reports the same errors. See also LLIST and LPOS. LPRINT USING isn’t supported; to format output for the printer, open PRN as a file and use PRINTF #n (see How to replace PRINT USING). LPRINT isn’t available on low memory systems.

LPRINT "Total:"; T

SCREEN

SCREEN [mode][,burst]

Sets the screen mode on a color adapter:

  • 0: text
  • 1: 320x200 graphics (4 colors)
  • 2: 640x200 graphics (2 colors)

A burst of 0 disables color in mode 0, and a burst of 1 disables color in mode 1. Changing the mode clears the screen and removes the console’s border, if any, so the console occupies the entire screen. Text output (eg, PRINT) works in all modes.

While a console is in any mode other than its original mode (eg, a graphics mode, or 40 columns in an 80-column console), it uses the entire screen, so other consoles on the same display are paused: any output they produce waits until that console returns to its original mode (eg, when its BAS program ends, which restores the mode), and then their borders are redrawn and their output continues. Their earlier screen contents are not restored.

A change from one text mode to another (40 or 80 columns, with or without color) in a full-screen console is the exception, on any display but a Monochrome Display: only that console changes. The other consoles keep running and keep their screen contents, and the display changes width whenever the focus moves to a console with a different width. A console that shares the screen with others, a graphics mode, and more than 25 rows (see WIDTH) still use the entire screen, as described above.

A mode change affects the entire screen, so a SCREEN statement that changes the mode in a console without the focus waits until the console gets the focus (eg, with Shift-Tab).

VIEW PRINT

VIEW PRINT [top TO bottom]

Limits scrolling to rows top through bottom (starting at 1), and moves the cursor to the first one: when output reaches the end of row bottom, only those rows scroll, and CLS clears only those rows, so the rows above and below them can hold headings or a status line. VIEW PRINT alone makes every row a scrolling row again.

Unlike Microsoft BASIC, the cursor isn’t confined to the scrolling rows: LOCATE can still move it to any row (eg, to update a status line), where output doesn’t scroll (below the scrolling rows, the cursor simply stops on the console’s last row). The rows remain in effect until the next VIEW PRINT, even after the program ends, or until SCREEN or WIDTH changes the mode.

CLS
PRINT "Squares"
VIEW PRINT 3 TO 10
FOR I = 1 TO 100: PRINT I, I * I: NEXT
VIEW PRINT

Rows outside the console are an “Illegal function call”, as is VIEW PRINT on a GENERIC terminal; an ANSI or VT100 terminal needs at least two scrolling rows. VIEW PRINT isn’t available on low memory systems (see Low Memory).

WIDTH

WIDTH 40|80|132[,rows]
WIDTH device,width

Sets the number of columns in text mode (which clears the screen). In a full-screen console, only that console changes (see SCREEN): other consoles are neither cleared nor paused, and the display changes width with the focus. In a console that shares the screen with others, asking for the console’s own width (eg, WIDTH 40 in a 40-column console) leaves the other consoles alone: the console is cleared and its border is removed, so the program has all the console’s columns and rows, until CLS at the prompt restores the border (a program can restore it with WIDTH 80, which also clears the console). In SCREEN 1, WIDTH 80 selects SCREEN 2, and in SCREEN 2, WIDTH 40 selects SCREEN 1.

rows sets the number of text rows as well: 25 on any display adapter, 43 on an EGA or VGA, or 50 on a VGA (eg, WIDTH 80,43). More than 25 rows are displayed with the adapter’s 8x8 font, in text mode only, and like any other mode change, they give the console the entire screen, without a border, until it returns to its original mode and 25 rows. The rows are set (and the screen is cleared) even if the columns aren’t changing, unless the console already has that many rows. Without rows, WIDTH leaves the rows alone if the columns aren’t changing; otherwise, as with SCREEN, the new mode has 25 rows. Rows that the adapter doesn’t support are an Illegal function call. If a program that used a graphics mode ends with more than 25 rows, the mode it started with is restored with 25 rows.

WIDTH also works on a serial console whose terminal type is VT100 (see CON): a VT100 has no 40-column mode, so WIDTH 40 displays each row in double-width characters instead, starting when the row is first written to or the cursor is moved to it. Other terminal types ignore WIDTH.

WIDTH 132 selects a VT100’s 132-column mode, which no display adapter has (on a video console, it’s an Illegal function call). A VT100 with the Advanced Video Option still has 24 rows then; without it, a VT100 has only enough memory for 14 rows of 132 columns, so the console has 14 rows until WIDTH 80 or WIDTH 40 restores all 24. BASIC-DOS asks the terminal which it is when the port is opened (and assumes 24 rows if a terminal doesn’t answer). Programs that ask for the console’s size (eg, VI, MORE, HELP, and DIR /W) use whatever the console has, and SCREEN 0 keeps the 132 columns.

With a device name (a string), WIDTH "SCRN:",width is the same as WIDTH width. For any other device (eg, WIDTH "COM1:",255), Microsoft BASIC sets the line width of the device’s output (where 255 means lines are never broken), but BASIC-DOS never breaks a device’s output into lines, so the width (1-255) is only checked, for compatibility. WIDTH device isn’t available on low memory systems (see Low Memory).

« Mouse CommandsGraphics Commands »

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