PC-BASIC 1.2.15
This is the documentation for PC-BASIC 1.2.15, last updated 2021-11-08 20:57:47.
Documentation for other versions of PC-BASIC:
This is the documentation for PC-BASIC 1.2.15, last updated 2021-11-08 20:57:47.
Documentation for other versions of PC-BASIC:
A free, cross-platform emulator for the GW-BASIC family of interpreters.
PC-BASIC is a free, cross-platform interpreter for GW-BASIC, Advanced BASIC (BASICA), PCjr Cartridge Basic and Tandy 1000 GWBASIC. It interprets these BASIC dialects with a high degree of accuracy, aiming for bug-for-bug compatibility. PC-BASIC emulates the most common video and audio hardware on which these BASICs used to run. PC-BASIC runs plain-text, tokenised and protected .BAS files. It implements floating-point arithmetic in the Microsoft Binary Format (MBF) and can therefore read and write binary data files created by GW-BASIC.
PC-BASIC is free and open source software released under the GPL version 3.
See also the PC-BASIC home page.
This quick start guide covers installation and elementary use of PC-BASIC. For more information, please refer to the full PC-BASIC documentation which covers usage, command-line options and a comprehensive GW-BASIC language reference. This documentation is also included with the current PC-BASIC release.
If you find bugs, please open an issue on GitHub. It would be most helpful if you could include a short bit of BASIC code that triggers the bug.
Packaged distributions can be downloaded from one of the following locations:
On Windows:
On Mac:
On Linux and other Unix:
sudo ./install.sh
. You may be asked to install further dependencies through your OS's package management system. pcbasic
on the command line. If the options above are not applicable or you prefer to install from source, please
consult INSTALL.md
for detailed instructions.
Click on the PC-BASIC application icon or run pcbasic
on the Windows, OSX or Linux command
line and PC-BASIC will start in direct mode with no program loaded. The default emulation target is
GW-BASIC 3.23 on a generic IBM-compatible PC with a VGA video card.
PC-BASIC starts in direct mode, a 1980s-style interface operated by executing BASIC commands directly. There is no menu, nor are there any of the visual clues that we've come to expect of modern software.
A few essential commands to help you get around:
Command | Effect |
---|---|
LOAD "PROGRAM" |
loads the program file named PROGRAM.BAS into memory |
LIST |
displays the BASIC code of the current program |
RUN |
starts the current program |
SAVE "PROGRAM",A |
saves the current program to a text file named PROGRAM.BAS |
NEW |
immediately deletes the current program from memory |
SYSTEM |
exits PC-BASIC immediately, discarding any unsaved program |
Use one of the key combinations Ctrl+Break
, Ctrl+Scroll Lock
, Ctrl+C
or F12+B
to interrupt a running program and return to direct mode.
By default, PC-BASIC looks for programs in your home folder.
C:\Users\
. You can find this folder in Windows Explorer by typing %USERPROFILE%
in the address bar.~/
.See the documentation on accessing your drives for more information.
The following pages have GW-BASIC program downloads, lots of information and further links.
DONKEY.BAS
. The first thing you'll see when starting PC-BASIC is the working environment. Like GW-BASIC, but unlike practically all modern compilers and interpreters, PC-BASIC's working environment serves both as a development environment and as a canvas on which to execute BASIC commands directly. With a few exceptions, practically all commands that can be run in the working environment can be used in a program, and vice versa.
The default PC-BASIC screen has 25 rows and 80 columns. The 25th row is used by PC-BASIC to show keyboard shortcuts, which means you can't use it to type on. In some video modes, there are only 40 or 20 columns.
Logical lines exceed the width of the physical row: if you keep typing beyond the screen width, the text will wrap to the next line but PC-BASIC will still consider it part of the same line. A logical line can be at most 255 characters long; if you type more than 255 characters, it will ignore the remainder. A line can also be wrapped by a line-feed, entered with Ctrl+Enter.
If you press Enter, PC-BASIC will attempt to execute the logical line on which the cursor is placed as a command. When the command is executed correctly, PC-BASIC will display the prompt Ok. If there is an error, it will display an error message followed by Ok. If the line starts with a number, it will be stored as a program line. No prompt is displayed.
The following keys have a special effect in the working environment:
↑ or Ctrl+6 | Move the cursor up, except at the top row. |
↓ or Ctrl+- | Move the cursor down, except at row 24. |
← or Ctrl+] | Move the cursor left. The left edge of the screen wraps around, except at the top row. |
→ or Ctrl+/ | Move the cursor right. The right edge of the screen wraps around, except at row 24. |
Ctrl+← or Ctrl+B |
Move to the first letter of the previous word. Words consist of
letters A—Z and figures 0—9 .
|
Ctrl+→ or Ctrl+F | Move to the first letter of the next word. |
Tab or Ctrl+I | Move the cursor to the next tab stop. Tab stops are 8 columns wide. |
Backspace or Ctrl+H | Delete the character left of the cursor, shift all further characters on the logical line one position to the left and change the attributes of those characters to the current attribute. At the left edge of the screen, this does the same as Del. |
Del or Ctrl+Backspace | Delete the character at the cursor and shift all further characters one position to the left, changing attributes to current. |
Esc or Ctrl+[ | Delete the current logical line. |
Ctrl+End or Ctrl+E | Delete all characters from the cursor to the end of the logical line. |
Ctrl+Break or Ctrl+C or Ctrl+Scroll Lock | Jump to the first column of the next line, without executing or storing the line under the cursor. |
Enter or Ctrl+M | Execute or store the current logical line. The complete line on the screen is considered part of the command, even if you did not type it. A line starting with a number is stored as a program line. |
End or Ctrl+N | Move the cursor to the first position after the end of the logical line. |
Home or Ctrl+K | Move the cursor to the top left of the screen. |
Ctrl+Home or Ctrl+L | Clear the screen and move the cursor to the top left of the screen. |
Ctrl+Enter or Ctrl+J | Move to the first column of the next line, connecting the two lines into one logical line. |
Ctrl+G | Beep the speaker. |
Pause or Ctrl+Num Lock | Pause. Press another key to resume. |
Ctrl+Prt Sc | Toggle echoing screen output to the printer (or other device attached to LPT1: ). |
Shift+Prt Sc | Print the screen. |
Ins or Ctrl+R | Toggle insert mode. In insert mode, characters are inserted rather than overwritten at the current location. If insertion causes the line to extend the physical screen width, the logical line extends onto the next line. Arrow keys exit insert mode. |
When a program is started, the commands in the program are followed until the program quits and returns to direct mode or until user input is required. When a program is running, a few keys have immediate effect:
Pause or Ctrl+Num Lock | Pause execution. Press another key to resume. |
Ctrl+Break or Ctrl+Scroll Lock | Stop execution and return to direct mode. A Break message is printed. |
Ctrl+C |
If ctrl-c-break=True : stop execution and return to direct mode.
A Break message is printed.
|
If user input is required by the statements INPUT
, LINE INPUT
, or RANDOMIZE
,
most keys have the same effect as in direct mode. The following keys have a different effect:
Ctrl+Break or Ctrl+C or Ctrl+Scroll Lock | Stop execution and return to direct mode. A Break message is printed. |
Enter | Finish input and return to the previous mode. |
The function keys and the alt key can be used as keyboard shortcuts for some keywords. The default values for the function keys are:
F1 | LIST |
F2 | RUN Enter |
F3 | LOAD" |
F4 | SAVE" |
F5 | CONT Enter |
F6 | ,"LPT1:" Enter |
F7 | TRON Enter |
F8 | TROFF Enter |
F9 | KEY Space |
F10 | SCREEN 0,0,0 Enter |
The function key shortcuts can be redefined with the KEY
statement.
The shortcuts are displayed at the bottom of the screen.
The following keywords can be entered with Alt+first letter. The Alt shortcuts cannot be redefined.
In PC-BASIC, the F12 key can be used to enter special keys that are not present on some keyboards.
F12+B | Break |
F12+P | Pause |
F12+C | Caps Lock |
F12+N | Num Lock |
F12+S | Scroll Lock |
The F12 key can also be used in combination with the regular number keys and arrow keys to enter numbers from the numeric keypad. The F12 combinations are not present in GW-BASIC.
Furthermore, as in GW-BASIC, the Alt key can be used to enter characters by their code points (ASCII values). This is done by pressing the Alt key and typing the code point as a decimal value on the numeric keypad, then releasing the Alt key.
Unlike in GW-BASIC, you can copy and paste text to the clipboard. This can be done with the mouse or with the F11 key.
Operating the clipboard with the mouse works in the style of X11: Left button is select and copy; middle button is paste.
The following keyboard combinations also operate the clipboard:
F11+↑↓←→ | Select a screen region. |
F11+A | Select all. |
F11+C | Copy to clipboard. |
F11+V | Paste from clipboard. |
In PC-BASIC, F11+F toggles fullscreen mode.
PC-BASIC can hold one BASIC program at a time in memory. To enter a program
line, start with a line number and enter BASIC commands after that.
The maximum length of a program line is 255 characters, including the line
number and any spaces. The program line will not be immediately executed, but
stored in the program. Program lines are sorted by line number, so that line
10
is executed before line 20
. All program
lines must have a line number. Line numbers range from 0
to 65535
inclusive.
It is not possible to enter a line number higher than 65529
, but these can
exist in loaded programs.
Within one program line, statements are separated by colons :
.
To run the program, type the command RUN
. PC-BASIC will now
execute all program lines in order inside the working environment. You cannot
move the cursor around or enter commands while the program is running. If and
when the program finishes, it will return control of the working environment to
you. You can interrupt a program at any time by using one of the key
combinations Ctrl+Break or Ctrl+Scroll
Lock. The program will stop immediately, print a Break
message and return control to you.
In GW-BASIC, you can not use Ctrl+C to interrupt a running program.
However, many modern keyboards do not have a Break or
Scroll Lock key, which would make it impossible to interrupt
a program that does not exit. Therefore, by default, PC-BASIC treats Ctrl+C
as if it were Ctrl+Break. Set the option ctrl-c-break=False
if you prefer the GW-BASIC style behaviour. When using the text-based or command-line interface,
this option is ignored.
A program can be stored on a drive by using the SAVE
command, in one of three ways:
SAVE "MYPROG",A
SAVE "MYPROG"
SAVE "MYPROG",P
In all three cases, the program will be written to the current working
directory with the name MYPROG.BAS
.
PC-BASIC can read and write Protected files created by GW-BASIC. Unlike
GW-BASIC, however, it does not disable accessing the unencrypted contents of the
file. The encryption used by GW-BASIC has been broken many decades ago, so
Protected mode offered little protection anyway; disallowing access is a small
security hazard as it would allow someone to send you a program that you cannot
inspect before running it. However, it is possible to disable access of
protected files by enabling the option strict-protect
.
You
can read a program file into memory with LOAD "MYPROG"
. This will
erase the program currently in memory and replace it with the one read from the
current working directory. To access files in a different directory, specify a path from the current
directory. The path specification follows DOS conventions. The only valid path
separator is the backslash \
. For example, LOAD "PROGRAMS\MYPROG"
.
You can load or run a program immediately on starting PC-BASIC by using the
load
or run
options.
For example,
pcbasic --run=MYPROG.BAS
The arguments to these options can be provided as PC-BASIC paths or as paths in the standard form for your operating system.
PC-BASIC can be used to convert between the three program formats: either by loading the program and saving
in your desired format, or from the command line using the convert
option. To convert a
tokenised or protected file to plain text you could use, for example:
pcbasic --convert=A PROGRAMP.BAS PROGRAMA.BAS
PC-BASIC emulates DOS disk devices, which are referred to by drive letters such as Z:
.
These devices can be mapped to locations in your file system.
By default, Z:
is PC-BASIC's current device.
If PC-BASIC is started from a start menu shortcut, the current device will be the shortcut's Start In folder.
%USERPROFILE%
on Windows. Uusually this will be a folder named something like
C:\Users\YourName
.
˜
.
This default location is where files will be saved to and loaded from in BASIC if you do not specify another device. Note that if PC-BASIC is started from the command prompt, the default location will be the current working directory.
Notes for Windows users
C:
on PC-BASIC is not your Windows C:
drive.
If you want PC-BASIC's drive letters to be the same as those in Windows, you have to explicitly
enable the option map-drives
. Use this with caution, since it
means that your programs can now read from and write to all drives that Windows
allows you access to.
C:\Program Files\PC-BASIC
,
Windows will move files written there to %LocalAppData%\VirtualStore
instead.
You can map drives and other file system locations as PC-BASIC devices by
using the mount
option in the configuration file or on the command prompt. For example,
on Windows, the option
mount=A:C:\Users\Me\BasicFloppy
will make the folder C:\Users\Me\BasicFloppy
available as PC-BASIC's A:
device.
On other platforms, an example mount option could look like
mount=A:/home/me/BasicFloppy
which would make the directory /home/me/BasicFloppy
available as PC-BASIC's A:
device.
PC-BASIC uses DOS conventions for filenames and paths. These are subtly different from Windows short filename conventions and not-so-subtly different from Unix conventions. This may lead to surprising effects in the presence of several files that match the same DOS name. To avoid such surprises, it's best to run PC-BASIC in a working directory of its own and use all-caps 8.3 format for all files.
Many BASIC dialects use the same extension .BAS
, but their files are not compatible.
PC-BASIC runs GW-BASIC program files only. Some tips to recognise GW-BASIC programs:
&hFF
.&hFE
.
In particular, QBASIC files (which have no line numbers) and QuickBASIC files
(magic byte &hFC
) will not run.
PC-BASIC will accept both DOS and Unix newline conventions for programs
stored as plain text. Any line not starting with a number will be considered a
continuation (through LF
) of the previous line.
This behaviour is different from GW-BASIC, which only
accepts text files with CR LF
line endings.
As a consequence, in exceptional cases where a program line is continued through LF
just before a number, correct GW-BASIC text files may not be loaded correctly.
If you encounter such a case, use
the strict-newline
option to enable GW-BASIC behaviour. If
strict-newline
is enabled, text files in standard Unix format
(LF
line endings, no end-of-file character) will fail to load. On
Linux or Mac, use a utility such as
unix2dos
to convert programs saved as text files before loading them. When saving as text,
PC-BASIC always uses CR LF
line endings and &h1A
at end-of-file.
PC-BASIC can run packaged programs. A package is simply a directory or zip archive.
The directory or zipfile contents will be loaded as the current working
directory. If a configuration file named PCBASIC.INI
is present
inside this directory, its settings are loaded; usually, one of those settings will be a
run
argument linking to a BASIC program enclosed in the archive or directory.
PC-BASIC will recognise zipfiles regardless of their extension.
A suggested extension for PC-BASIC packages is .BAZ
.
Packages are a convenient choice if a program needs to change many PC-BASIC options
to function as desired, or if it needs a particular working directory setup.
Zipfile packages are unpacked to a temporary directory each time they are loaded. The temporary directory is removed when PC-BASIC closes. With zipfile packages, it is therefore not possible to save files and re-open them on the next run of the package.
The CAS1
device interfaces with the cassette tape emulator.
Tapes were never very popular on the IBM PC, and indeed only available with the
original PC and the PCjr. There are not many IBM PC cassettes in the wild.
However, should you come across one, all you have to do to read it with PC-BASIC
is record it into a .WAV
(RIFF WAVE) file and attach it to the CAS1:
device with the cas1=WAV:filename
option.
You can also generate your own tape images and store your programs on it. WAV
files generated by PC-BASIC are large but very easily compressed in a ZIP
archive; this works better and leads to smaller files than transcoding to a lossy
audio format like MP3
.
As an alternative to .WAV
, you can store tapes in CAS
format. This is simply a bit-dump of the tape and is interchangeable
with tape images for the PCE IBM PC emulator.
Previous versions of PC-BASIC included support for BASICODE cassettes; this has been discontinued in favour of a separate BASICODE decoder. Use this decoder to convert the BASICODE program to PC-BASIC format before loading it into PC-BASIC.
PC-BASIC makes some default choices with basic security in mind, but does not
sandbox its programs in any meaningful way. BASIC programs have more or less
full access to your computer. You should treat them with the same caution as
you would shell scripts or binaries. Therefore, do not run a program from the
internet that you have not inspected first using LIST
or
pcbasic --convert=A filename
on the command line. You wouldn't just download
an executable from the internet and run it either, right?
You can print from PC-BASIC programs
by accessing the LPT1:
device. PC-BASIC will send the output to
your operating system's default printer, unless you change the lpt1=
option. To print through a printer named MyPrinter
, set
lpt1=PRINTER:MyPrinter
. You can also attach printers to the
LPT2:
and LPT3:
devices.
The output will be sent to the printer when you close PC-BASIC. If you prefer,
you can instead send every page separately to the printer by setting
print-trigger=page
. You can even send every line separately, but
this only makes sense on a tractor-fed printer (as was common in GW-BASIC's
heyday).
It's easy to print to a file instead of a printer:
set lpt1=FILE:output.txt
to send all LPT1:
printer output to the text file output.txt
.
The printing statements LPRINT
and LLIST
always send
their output to PC-BASIC's LPT1:
device.
The presentation of printed documents is left to your operating system: it
will be the default presentation of text files. If you wist to change the way
documents are printed, please refer to your OS's settings. On Windows, for example, text files
are printed by notepad.exe
and changing the default settings in that
application will change the way PC-BASIC documents are printed. You will need to set a
printer font that includes the characters you need to print. On Unix systems,
PC-BASIC will use the paps
utility if it is available; this will
automatically select fonts that support the characters you need.
PC-BASIC provides the serial devices COM1:
and COM2:
.
To make use of these, you need to attach them to a communications port on your
computer with the com1=
or com2=
option. To attach to
the first physical serial port, set com1=PORT:0
(or, alternatively,
com1=PORT:COM1
on Windows or
com1=PORT:/dev/ttyS0
on
Linux). If you do not have a serial port, you can emulate one by sending the
communications over a network socket: set com1=SOCKET:localhost:7000
and all COM1:
traffic will be sent through socket 7000
.
To access a parallel port, attach it to one of LPT1:
, LPT2:
or LPT3:
.
For example, set lpt2=PARPORT:0
to attach your computer's first
parallel port to LPT2:
.
By default, PC-BASIC emulates GW-BASIC on a system with VGA video capabilities.
However, it can emulate several other setups, which differ from each other in
terms of video and audio capacity, fonts, memory size, as well as available BASIC syntax.
The easiest way to set the emulation target is by using a preset
option.
For example, run pcbasic --preset=pcjr
.
Other available emulation target presets are:
Preset | Emulation target |
---|---|
pcjr |
IBM PCjr with Cartridge BASIC, including PCjr video and 3-voice sound capabilities and extended BASIC syntax. |
tandy |
Tandy 1000 with GW-BASIC, including Tandy video and 3-voice sound capabilities and extended BASIC syntax. |
olivetti |
Olivetti M24 or AT&T PC 6300. |
cga |
IBM or compatible with Color/Graphics Adapter and a composite monitor. This enables composite colorburst emulation. |
ega |
IBM or compatible with Extended Graphics Adapter. |
vga |
IBM or compatible with Video Graphics Array. |
mda |
IBM or compatible with Monochrome Display Adapter and green-tinted monochrome monitor. |
hercules |
IBM compatible with Hercules Graphics Adapter and green-tinted monochrome monitor. |
strict |
Choose strict compatibility with GW-BASIC over convenience, security, rhyme or reason. |
Presets are groups of options that are defined in the default configuration
file. You can create your own presets by creating a header in your private configuration
file with the name of the new preset, followed by the options you want to apply. For example,
if you define:
[my_preset]
you can now run
video=vga
syntax=pcjr
pcbasic --preset=my_preset
to start an emulation of
a hypothetical machine with a VGA video card running PCjr Cartridge BASIC.
PC-BASIC aims for a very high level of compatibility with GW-BASIC. However,
some compatibility features are disabled by default for convenience or security reasons.
These features can be switched on using individual command-line options. The highest level of
compatibility with GW-BASIC can be attained by setting
preset=strict
,
which switches off all convenience and security features that cause differences with
GW-BASIC.
PC-BASIC supports a large number of legacy codepages that were common at the
time GW-BASIC was popular, including double-byte character set codepages used
for Chinese, Japanese and Korean. You can select your codepage by using the
codepage=
option. For example, codepage=936
selects
the GBK codepage commonly used on the Chinese mainland. PC-BASIC will load and
save all program files as if encoded in the codepage you select.
It is also possible to load and save programs in the nowadays common UTF-8
standard format, by enabling the utf8
option. When
utf8
is enabled, plain-text program source will be saved and loaded in
standard UTF-8 encoding. Please note that you will still need to select a
codepage that provides all the Unicode characters that your program needs.
Note that PC-BASIC does not implement the following features relevant to some of these codepages:
874
and 1258
) are therefore not
shown correctly: instead of being combined with their preceding base character as a single combined glyph,
such combinations will be shown as separate glyphs. Where available, alternative codepages with precomposed
characters will give better results. This affects code pages marked with C in the table.
The following codepages are available. PC-BASIC uses the Microsoft OEM codepage number where
this is unambiguous. The code pages are expected to agree with Microsoft sources for the ranges
&h80
–&hFF
. Ranges &h00
–&h1F
and &h7F
are implemented as the IBM Special Graphic Characters where some
code page sources will list these as the corresponding control characters.
For unofficial codepages and those with conflicting numbering, codepage
names are used instead of numbers.
codepage_id |
Codepage | Languages | Notes |
---|---|---|---|
437 |
DOS Latin USA | English | |
720 |
Transparent ASMO | Arabic | B |
737 |
DOS Greek | Greek | |
775 |
DOS Baltic Rim | Estonian, Latvian and Lithuanian | |
806 |
IBM-PC Devanagari | Hindi | |
850 |
DOS Latin 1 | Western European languages | |
851 |
DOS Greek 1 | Greek | |
852 |
DOS Latin 2 | Central European languages | |
853 |
DOS Latin 3 | Southern European languages | |
855 |
DOS Cyrillic 1 | Serbian, Macedonian and Bulgarian | |
856 |
DOS Hebrew | Hebrew | B |
857 |
DOS Latin 5 | Turkish | |
858 |
DOS Latin 1 with Euro | Western European languages | |
860 |
DOS Portuguese | Portuguese | |
861 |
DOS Icelandic | Icelandic | |
862 |
DOS Hebrew | Hebrew | B |
863 |
DOS Canadian French | French | |
864 |
DOS Arabic | Arabic | B |
865 |
DOS Nordic | Danish and Norwegian | |
866 |
DOS Cyrillic 2 | Russian | |
868 |
DOS Urdu | Urdu | B |
869 |
DOS Greek 2 | Greek | |
874 |
TIS-620 | Thai | C |
932 |
Shift-JIS (variant) | Japanese | |
934 |
DOS/V Korea | Korean | |
936 |
GBK; GB2312/EUC-CN superset | Simplified Chinese | |
938 |
DOS/V Taiwan | Traditional Chinese | |
949 |
IBM-PC Korea KS; EUC-KR superset | Korean | |
950 |
Big-5 (variant) | Traditional Chinese | |
1258 |
Vietnamese | Vietnamese | C |
alternativnyj |
GOST Alternativnyj Variant | Russian | |
armscii8a |
ArmSCII-8a; FreeDOS cp899 | Armenian | |
big5-2003 |
Big-5 (Taiwan 2003) | Traditional Chinese | |
big5-hkscs |
Big-5 (Hong Kong 2008) | Traditional Chinese | |
georgian-academy |
Academy Standard | Georgian | |
georgian-ps |
Parliament Standard | Georgian | |
iransystem |
Iran System | Persian | B |
iscii-as |
ISCII Assamese | Assamese | C |
iscii-be |
ISCII Bengali | Bengali | C |
iscii-de |
ISCII Devanagari | Hindi, Marathi, Sanskrit, Konkani, Nepali | C |
iscii-gu |
ISCII Gujarati | Gujarati | C |
iscii-ka |
ISCII Kannada | Kannada | C |
iscii-ma |
ISCII Malayalam | Malayalam | C |
iscii-or |
ISCII Oriya | Oriya | C |
iscii-pa |
ISCII Punjabi | Punjabi | C |
iscii-ta |
ISCII Tamil | Tamil | C |
iscii-te |
ISCII Telugu | Telugu | C |
kamenicky |
Kamenický; cp895 | Czech | |
koi8-r |
KOI8-R | Russian | |
koi8-ru |
KOI8-RU | Ukrainian, Belarusian, Russian | |
koi8-u |
KOI8-U | Ukrainian, Russian | |
mazovia |
Mazovia; cp667, 991, 790 | Polish | |
mik |
MIK, FreeDOS cp3021 | Bulgarian | |
osnovnoj |
GOST Osnovnoj Variant | Russian | |
pascii |
PASCII | Kashmiri, Persian, Sindhi, Urdu | B |
ruscii |
RUSCII | Ukrainian, Russian | |
russup3 |
Cornell Russian Support for DOS v3 | Russian | |
russup4ac |
Exceller Software Russian Support for DOS v4 Academic | Russian | |
russup4na |
Exceller Software Russian Support for DOS v4 Non-Academic | Russian | |
viscii |
VISCII, FreeDOS cp30006 | Vietnamese |
You can add custom codepages to PC-BASIC, by adding a file with
its mapping to Unicode to the codepage/
directory.
PC-BASIC emulates the distinctive raster fonts of IBM-compatible machines. The ROM fonts of the original IBM and Tandy adapters (which are in the public domain in a number of countries) have been included in PC-BASIC. These provide the most accurate emulation. However, the font ROMs only included a single code page – DOS Latin USA 437.
To support code pages beyond 437, PC-BASIC defaults to the CPIDOS font used by default in FreeDOS and DOSBox. This font is very similar in style to the IBM VGA font but has support for many more code pages, in particular Western and Middle Eastern alphabets. If CPIDOS does not include the characters you need, PC-BASIC tries to find them in UNI-VGA, which is also very similar in style to VGA. If that does not suffice, PC-BASIC falls back to GNU UniFont for the missing characters. UniFont's Western glyphs are less similar to the VGA font, but it provides support for the full Unicode Basic Multilingual Plane. For example, all Chinese, Japanese and Korean glyphs in PC-BASIC are taken from UniFont.
It is possible to change the choice of font using the font=
option.
You can provide a list of fonts, where the last font specified is the
most preferred one.
PC-BASIC reads fonts in the .hex
format introduced by UniFont. It's
easy to define custom fonts in this format: it can be edited in a regular text editor.
See the UniFont project for an authoring tool. You can add custom fonts to PC-BASIC by
installing them into the font/
subdirectory of PC-BASIC's installation
directory.
By default, the following fonts are available:
font_name |
Name | Sizes | Codepages |
---|---|---|---|
unifont |
GNU UniFont | 16 | all |
univga |
Uni-VGA font | 16 | many |
freedos |
FreeDOS CPIDOS font | 8, 14, 16 | many |
cga |
IBM Colour/Graphics Adapter font | 8 | 437 only |
mda |
IBM Monochrome Display Adapter font | 14 | 437 only |
vga |
IBM Video Graphics Array font | 8, 14, 16 | 437 only |
olivetti |
Olivetti/AT&T font | 16 | 437 only |
tandy1 |
Tandy-1000 font old version | 8 | 437 only |
tandy2 |
Tandy-1000 font new version | 8 | 437 only |
GNU UniFont contains glyphs for all the defined code points of the Basic Multilingual Plane of Unicode 7.0, which makes it an excellent fallback font. Its glyphs are not, however, very similar to those that were used on DOS machines; both Uni-VGA and the FreeDOS CPIDOS fonts are therefore more suitable, when they have the required glyphs.
PC-BASIC supports redirecting input and output the GW-BASIC way: output redirected
with the output=
option will be sent to the screen as well as
the specified file, while input redirected with input=
is taken
only from the specified file. Note that screen output through the
SCRN:
device and keyboard input through the KYBD:
device are not redirected. Files are read and written in the codepage set with
PC-BASIC.
Note that it is also possible to use your operating system's facility to
redirect console output using the <
and >
operators. It's best to set interface=none
so that I/O is
redirected through the console. This will produce files in your console's standard encoding,
which is often UTF-8 on Unix and Windows-1252 on Windows.
You can run PC-BASIC as a
command-line interface by setting the interface=cli
(or
-b
) option. No window will be opened: you can type BASIC commands
straight into your Command Prompt/Terminal. Use the horizontal arrow keys to
move on the current line you're editing; use the vertical arrow keys to show
screen rows above and below. Copy and paste are available only if the calling
shell provides them. On Windows, Ctrl+Break will
terminate PC-BASIC immediately. You can use Ctrl+C to
interrupt the program. The end-of-file key combination
(Ctrl+D on Unix, Ctrl+Z on Windows)
will exit PC-BASIC.
You can use the command-line interface to run one or a few BASIC commands directly, like so:
me@mybox$ pcbasic -bqe="?1+1" 2 me@mybox$
For scripting purposes, it is also possible to run PC-BASIC without any
interface by setting interface=none
or
-n
. If this is
set, PC-BASIC will take input from and send output to the console as UTF-8
without further modification. This is useful in combination with redirection and
pipes.
There is also a full-screen text interface available: enable it
by setting interface=text
(or -t
). The text-based
interface is very similar to the default graphical interface, but runs in your
Command Prompt or Terminal window.
In the text-based and command-line interfaces, graphics are not available. Attempting to open a graphical screen mode will lead to an Illegal function call error. Furthermore, many Ctrl and Alt key combinations are not available.
On Unix systems only, you can get sound in the text and command-line
interfaces over the PC speaker if you install the beep
utility and
enable the legacy PC-speaker driver or emulation.
PC-BASIC has a number of settings that change the way it operates. These settings can be changed by setting options on the command line or through editing the configuration file.
In either method, the options have the same name and syntax. In what follows, we will often refer to a particular option setting; remember that you can set this from the command line as well as from the configuration file.
You can enter command-line options if you start PC-BASIC from your operating system's command prompt, console or terminal
(the C:\>
prompt on Windows),
by supplying the option with two dashes in front, like so:
pcbasic --preset=tandy --ctrl-c-break=True
On the command line, you can leave out the expression =True
that is common in switching options.
Some options have an alternative, short name consisting of a single
letter preceded by a single dash, which you can use on the command line.
You can combine multiple short options with a single dash.
You can change options by adding or removing lines in your local configuration file, which can be found in the following location:
%AppData%\pcbasic-1.2\PCBASIC.INI
~/Library/Application Support/pcbasic-1.2/PCBASIC.INI
~/.config/pcbasic-1.2/PCBASIC.INI
Change an option in the configuration file by adding a line in the section named [pcbasic]
, like so:
[pcbasic]
preset=tandy
ctrl-c-break=True
You cannot use positional arguments or
the short name of options in the configuration file.
You also cannot leave out the expression =True
.
The configuration file should be a text file encoded in ASCII or UTF-8.
pcbasic
[program|package
[output]]
[--allow-code-poke[=True|=False]]
[--altgr[=True|=False]]
[--append[=True|=False]]
[--aspect=x,y]
[-b]
[--border=width]
[--caption=title]
[--capture-caps[=True|=False]]
[--cas1=type:value]
[--cga-low[=True|=False]]
[--codepage=codepage_id]
[--config=config_file]
[--com1=type:value]
[--com2=type:value]
[--convert={A|B|P}]
[--copy-paste=copy_button,paste_button]
[--ctrl-c-break[=True|=False]]
[--current-device={CAS1|@|A|B ... |Z}]
[--dimensions=x,y]
[-d]
[--double[=True|=False]]
[-e=command_line]
[--exec=command_line]
[--font=font_name[,font_name ... ]]
[--fullscreen[=True|=False]]
[-h]
[--help]
[-i]
[--input=input_file]
[--interface={none|cli|text|graphical}]
[-k=keystring]
[--keys=keystring]
[-l=program]
[--load=program]
[--logfile=log_file]
[--lpt1=type:value]
[--lpt2=type:value]
[--lpt3=type:value]
[--map-drives[=True|=False]]
[-f=number_of_files]
[--max-files=number_of_files]
[-m=max_memory[,basic_memory_blocks]]
[--max-memory=max_memory[,basic_memory_blocks]]
[-s=record_length]
[--max-reclen=record_length]
[--monitor={rgb|composite|mono}]
[--mono-tint=r,g,b]
[--mount=drive:path,[drive:path ... ]]
[-n]
[--nobox[=True|=False]]
[--nokill[=True|=False]]
[--nosound[=True|=False]]
[--output=output_file]
[--pcjr-term=terminal_program]
[--peek=[seg:addr:val[,seg:addr:val ... ]]]
[--pen={left|middle|right|none}]
[--preset=option_block]
[--print-trigger={line|page|close}]
[-q]
[--quit[=True|=False]]
[--reserved-memory=number_of_bytes]
[--resume[=True|=False]
[-r=program]
[--run=program]
[--scaling={smooth|crisp|native}]
[-c=size]
[--serial-buffer-size=size]
[--shell={none|native|command]]
[--state=state_file]
[--strict-hidden-lines[=True|=False]]
[--strict-newline[=True|=False]]
[--strict-protect[=True|=False]]
[--syntax={advanced|pcjr|tandy}]
[-t]
[--text-width={40|80}]
[--utf8[=True|=False]]
[-v]
[--version]
[--video=card]
[--video-memory=size]
[-w]
[--wait[=True|=False]]
program
.BAS
program is specified as the first positional argument,
it will be run.
The
--run
,
--load
and
--convert
options
override this behaviour.
package
PCBASIC.INI
will be loaded; usually, it will run a program file in the package.
All other command-line options will override the package configuration file,
note in particular the potential of the
--run
,
--load
and
--convert
options
to alter the behaviour of the package.
output
--convert
option is given.
--allow-code-poke[=True|=False]
POKE
into code memory.
--altgr[=True|=False]
True
(default), interpret the right
Alt key as Alt Gr instead of Alt.
The left Alt key is always seen as Alt.
--append[=True|=False]
--output=output_file
,
the output_file
is appended to rather than overwritten.
--aspect=x,y
x
:y
.
Only has an effect if combined with --interface=graphical
.
-b
--interface=cli
.
--border=width
--interface=graphical
.
title
is PC-BASIC.
--capture-caps[=True|=False]
--interface=graphical
.
--cas1=type:value
CAS1:
cassette device.
type:value
can be
WAV:wav_file
wav_file
with data modulated in IBM PC cassette format.
CAS:cas_file
cas_file
.
--cga-low[=True|=False]
--video={cga|cga_old|ega|vga}
.
--codepage=codepage_id
codepage/
directory; by default, these are:
437
720
737
775
806
850
851
852
853
855
856
857
858
860
861
862
863
864
865
866
868
869
874
932
934
936
938
949
950
1258
alternativnyj
armscii8a
big5-2003
big5-hkscs
georgian-academy
georgian-ps
iransystem
iscii-as
iscii-be
iscii-de
iscii-gu
iscii-ka
iscii-ma
iscii-or
iscii-pa
iscii-ta
iscii-te
kamenicky
koi8-r
koi8-ru
koi8-u
mazovia
mik
osnovnoj
pascii
ruscii
russup3
russup4ac
russup4na
viscii
--config=config_file
--com1=type:value
COM1:
serial device.
type:value
can be one of the following.
PORT:device_name
device_name
can be a device name such as COM1
or
/dev/ttyS0
or a number,
where the first serial port is number 0.
SOCKET:host:socket
STDIO[:[CRLF]]
CRLF
is specified, PC-BASIC replaces CR
characters with LF
on its output and LF
with CR
on its input. This is more intuitive on Unix shells.
When using a Unix console, you should use stty -icanon
to enable PC-BASIC to read input correctly.
COM1:
device is
unavailable.
--com2=type:value
COM2:
serial device. See
--com1
.
--convert={A|B|P}
A
B
P
output
is not specified, write to
standard output. If program is not specified, use the argument of
--run
or
--load
. If none of those are
given, read from standard input. Overrides
--resume
,
--run
and --load
.
--copy-paste=copy_button,paste_button
copy_button
and paste_button
are
chosen from left
,middle
,right
,none
.
--ctrl-c-break[=True|=False]
False
, follow GW-BASIC behaviour
where Ctrl+C breaks AUTO
and INPUT
but not program execution or
LIST
.True
, treat
Ctrl+C exactly like
Ctrl+Break and
Ctrl+Scroll Lock when --interface=graphical
.--interface={text|cli}
,
Ctrl+C is always treated like
Ctrl+Break.True
.
--current-device={CAS1|@|A|B ... |Z}
CAS1
for the cassette device. The device chosen
should be mounted to an actual location using
--mount
(or --cas1
if the cassette device is chosen). Default is Z
,
with the Z:
device mounted to your current drive.
--dimensions=x,y
x
by
y
pixels. This overrides
--scaling=native
and --aspect
.
Only has an effect if combined with --interface=graphical
.
-d
--double[=True|=False]
/d
option in GW-BASIC.
-e=command_line
--exec=command_line
command_line
. The specified
commands are executed before entering into direct mode or
running a program.
--font=font_name[,font_name ... ]
unifont,univga,freedos
(i.e. the
freedos
font has preference). The available fonts
are stored in font/
. By default, the following fonts are
available:
unifont
univga
freedos
cga
mda
vga
olivetti
tandy1
tandy2
--fullscreen[=True|=False]
--interface=graphical
.
-h
--help
-i
/i
.
--input=input_file
input_file
,
except if KYBD:
is read explicitly. Input from
KYBD:
files is always read from the keyboard,
following GW-BASIC behaviour.
--interface={none|cli|text|graphical}
none
-n
.cli
-b
.text
-t
.graphical
graphical
.
-k=keystring
--keys=keystring
keystring
into the keyboard buffer.
-l=program
--load=program
program
loaded.
--logfile=log_file
log_file
instead of stderr
.
--lpt1=type:value
LPT1:
parallel device.
type:value
can be
PRINTER:printer_name
printer_name
is not specified, the default
printer is used.
FILE:file_name
/dev/stdout
on Unix or LPT1
on Windows.
STDIO[:[CRLF]]
CRLF
is specified, PC-BASIC replaces CR
characters with LF
on its output. This is more intuitive on Unix shells.
PARPORT:port_number
port_number
is 0
for the first parallel port, etc.
PARPORT
only works with physical parallel ports; for example, a Windows printer or other
device mapped with NET USE LPT1:
can only be attached with FILE:LPT1
LPT1:
is connected to the default printer.
--lpt2=type:value
LPT2:
parallel device.
See --lpt1
.
If this option is not specified, LPT2:
is unavailable.
--lpt3=type:value
LPT3:
parallel device.
See --lpt1
.
If this option is not specified, LPT3:
is unavailable.
--map-drives[=True|=False]
Z:
C:
H:
-f=number_of_files
--max-files=number_of_files
number_of_files
. This is
equivalent to the /f
option in GW-BASIC.
Default is 3
.
-m=max_memory[,basic_memory_blocks]
--max-memory=max_memory[,basic_memory_blocks]
max_memory
and the maximum size of the data
memory available to BASIC to
basic_memory_blocks*16
. In PC-BASIC, the
minimum of these values is simply the data memory size; the two
values are allowed for compatibility with the
/m
option in GW-BASIC.
-s=record_length
--max-reclen=record_length
RANDOM
files to
record_length
. Default is 128
, maximum is
32767
. This is equivalent to the
/s
option in GW-BASIC.
--monitor={rgb|composite|mono}
rgb
composite
mono
SCREEN 2
with
--video={pcjr|tandy|cga|cga_old}
,
--monitor=composite
enables (crude) colour artifacts.
--mono-tint=r,g,b
r,g,b
, each in the range 0—255.
Only has an effect if combined with --monitor=mono
.
--mount=drive:path,[drive:path ... ]
path
to drive letter drive:
.
The path can be absolute or relative. By
default, Z:
is assigned to the current working
directory and no other drive letters are assigned.
-n
--interface=none
.
--nobox[=True|=False]
--nobox
is set, they will be displayed as DBCS.
--nokill[=True|=False]
--nokill
to allow BASIC to capture
Alt+F4 instead. This is useful if
your program uses this key combination.
--nosound[=True|=False]
--output=output_file
output_file
, except
if SCRN:
is written to explicitly. Output to
SCRN:
files will always be shown on the screen, as in
GW-BASIC.
--pcjr-term=terminal_program
TERM
command to terminal_program
. This only has an
effect with --syntax={pcjr|tandy}
.
--peek=[seg:addr:val[,seg:addr:val ... ]]
PEEK
preset values. If defined,
DEF SEG:? PEEK(addr)
will return
val.
--pen={left|middle|right|none}
left
.
If set to none
, light pen emulation is switched off.
On Android, left
means touch input.
--preset=option_block
[this]
--preset=this
will load all
settings defined in that section. Available presets depend on your
configuration file. See the list of default presets in the User's Guide.
--print-trigger={line|page|close}
line
page
close
close
.
-q
--quit[=True|=False]
--run
, PC-BASIC quits when the program
ends. If set in direct mode, PC-BASIC quits after the first
command is executed.
--reserved-memory=number_of_bytes
number_of_bytes
of memory at the
bottom of the data segment. For compatibility with GW-BASIC.
Default is 3429
bytes. Lowering this value makes more string and
variable space available for use by programs.
--resume[=True|=False
--run
and
--load
.
-r=program
--run=program
program
. Overrides
--load
.
--scaling={smooth|crisp|native}
smooth
crisp
smooth
,
but without smoothing.
native
--scaling=native
overrides --aspect.
smooth
.
Only has an effect if combined with --interface=graphical
.
-c=size
--serial-buffer-size=size
size
. Default is
256
. If set to 0
, serial communications are disabled.
--shell={none|native|command]
SHELL
command to the operating system's native shell or a custom shell
run by command
. Default is none
,
which disables the SHELL
command.
--state=state_file
state_file
.
Default is PCBASIC.SAV
in the Application Data
directory.
65530
, as in
GW-BASIC. Use with care as this allows execution of hidden
lines of code.
--strict-newline[=True|=False]
CR
and LF
in files strictly
like GW-BASIC. On Unix, you will need to convert your files to DOS
text first if using this option.
--strict-protect[=True|=False]
--syntax={advanced|pcjr|tandy}
advanced
pcjr
tandy
advanced
.
-t
--interface=text
.
--text-width={40|80}
80
.
--utf8[=True|=False]
True
,
programs stored as plain text will be converted
from UTF-8 on LOAD
and to UTF-8 on
SAVE
. If False
,
the PC-BASIC codepage will be used.
-v
--version
--video=card
vga
ega
cga
cga_old
mda
hercules
pcjr
tandy
olivetti
vga
.
--video-memory=size
CLEAR
statement;
at least 32768 needs to be available to enter
SCREEN 5
and SCREEN 6
.
Default is 16384
or PCjr and Tandy and 262144
on other
machine presets.
-w
--wait[=True|=False]
True
, PC-BASIC waits for a keystroke before
closing the window on exit. Only works for
--interface=graphical
or
--interface=text
. Default is False
.
GW-BASIC recognised a number of DOS-style command-line options on the command-line when invoking it from DOS
with a command like BASIC
, BASICA
, or GWBASIC
.
These are matched by PC-BASIC with only minor modifications, usually just replacing the
forward slash /
with a dash -
. The GW-BASIC syntax is shown here
for reference only; only the syntax with the dash works with PC-BASIC.
/d
becomes
-d
/f:n
becomes
-f=n
/s:n
becomes
-s=n
RANDOM
files.
/c:n
becomes
-c=n
COM
devices.
/i:n
becomes
-i=n
/m:n,m
becomes
-m=n,m
n
and maximum
BASIC memory size to m*16
bytes.
>filename
becomes
--output=filename
filename
.
>>filename
becomes
--output=filename --append
filename
.
<filename
becomes
--input=filename
filename
.
pcbasic
pcbasic --codepage=950
pcbasic Foobar.baz
pcbasic Foobar.baz --convert=A --utf8
pcbasic MYPROG.BAS --mount=A:./files,B:./morefiles
files
as drive A:
and subdirectory morefiles
as
drive B:
, then run MYPROG.BAS
.
pcbasic --mount=A:C:\fakeflop
C:\fakeflop
mounted as
A:
drive.
pcbasic Z:\INFO.BAS --preset=mda --mono-tint=255,128,0
INFO.BAS
in the current directory on an
emulated MDA with amber tinted monitor.
pcbasic /home/me/retro/COMP.BAS --preset=cga --monitor=composite
COMP.BAS
stored at /home/me/retro
on an emulated CGA machine with a composite monitor.
pcbasic PCJRGAME.BAS --preset=pcjr -k='start\r'
PCJRGAME.BAS
on an emulated PCjr and feed in
the keystrokes startEnter.
pcbasic BANNER.BAS --lpt2=PRINTER:
BANNER.BAS
in default mode with the default
printer attached to LPT2:
.
pcbasic --resume
pcbasic -qbe="?1+1"
PRINT 1+1
in the
command-line interface and return to the calling shell.
This documentation describes the PC-BASIC language, which aims to faithfully emulate GW-BASIC 3.23, IBM Advanced BASIC, IBM Cartridge BASIC and Tandy 1000 GW-BASIC.
The BASIC Language Guide covers the language topic by topic, thematically grouping language elements used for a related purpose. Please refer to the BASIC Language Reference for a formal description of the langage elements and their syntax.
Statement | Description |
---|---|
AUTO |
Enter automatic line numbering mode |
CHAIN |
Load a new program and run it, preserving common variables |
COMMON |
Set common variables |
DELETE |
Delete lines from the program |
EDIT |
Print a program line to the screen for editing |
LIST |
Print program lines to the screen |
LLIST |
Print program lines to the printer |
LOAD |
Read a new program from file |
MERGE |
Overlay a program file onto the current program |
NEW |
Clear the current program from memory |
RENUM |
Replace the program's line numbers |
RUN |
Start the current program |
SAVE |
Store the current program to file |
TRON |
Enable line number tracing |
TROFF |
Disable line number tracing |
SYSTEM |
Exit the BASIC interpreter |
A program is normally executed starting with its lowest line number (or the line number called by RUN
). Statements on a line are executed from
left to right. When all statements on a line are finished, execution moves to the next lowest line number, and so on until no line numbers are left.
Control flow statements can be used to modify this normal flow of executon.
The END
and STOP
statements serve
in a program to stop its execution and return to direct mode. When STOP
is used, a
Break message is printed. From
direct mode, CONT
can be executed to resume the program where
it was stopped. While END
seems intended to terminate the program,
it does not preclude the user from resuming it with CONT
.
Unconditional jumps can be made with GOTO
. The program flow will
continue at the line number indicated in the GOTO
statement. Due to the PC-BASIC language's lack of
sophisticated looping, branching and breaking constructs, unconditional jumps are essential and used frequently.
The GOSUB
statement jumps to a subroutine. Similar to GOTO
, this is an unconditional jump;
however, the location of the call is stored and the program will continue its flow there after the subroutine terminates
with a RETURN
statement. Subroutines are somewhat like procedures in that they allow chunks of code that perform a given task to be separated from
the main body of the program,
but they do not have separate scope since all variables in
PC-BASIC are global. They do not have return values. It is even possible to jump out of a subroutine to anywhere in the program by
supplying the RETURN
statement with a line number.
The ON
statement provides an alternative branching construct. An integer value is used to selects
one of a list of line numbers, and execution is continued from there. It can be used with a GOTO
jump
as wellas with a GOSUB
subroutine call.
ON
, GOTO
and GOSUB
can also be used from direct mode to start a program or subroutine without resetting variables.
The IF–THEN–ELSE
construct tests for a condition and execute different code branches based on its truth value.
This is not a block construct; all code in the THEN
and ELSE
branches must fit on one line. For this reason, branching is often used in combination with
GOTO
jumps. For example:
10 INPUT "How old are you"; AGE%
20 IF AGE%>30 THEN 100
30 IF AGE%<30 THEN 200 ELSE PRINT "You are 30 years old."
40 END
100 PRINT "You are over 30."
110 END
200 PRINT "You are not yet 30."
210 END
The WHILE–WEND
looping construct repeats the block of code between WHILE
and WEND
as long as a given condition remains true.
The FOR–NEXT
construct repeats a block of code while a counter remains in a given range. The counter is set to a starting value at the first pass of the
FOR
statement and incremented by the STEP
value at each pass of NEXT
.
For example:
10 FOR I=1 TO 10
20 PRINT STRING$(I, "*"); USING " [##]"; I
30 NEXT I
Looping constructs may be nested.
Control flow is also affected by event and error trapping.
Statement | Description |
---|---|
CONT |
Continue interrupted program |
ELSE |
Ignore the remainder of the line (standalone ELSE ) |
END |
Stop execution of the program |
FOR |
Start a for-loop |
GOSUB |
Call a subroutine |
GOTO |
Jump to another location in the program |
IF |
Branch on a condition |
NEXT |
Iterate a for-loop |
ON |
Calculated jump or subroutine call |
RETURN |
Return from subroutine |
STOP |
Interrupt program execution |
WEND |
Iterate a while-loop |
WHILE |
Enter a while-loop |
Statement | Description |
---|---|
DEFDBL |
Specify variable name range for double-precision floats |
DEFINT |
Specify variable name range for integers |
DEFSNG |
Specify variable name range for single-precision floats |
DEFSTR |
Specify variable name range for strings |
DIM |
Allocate an array |
ERASE |
Deallocate an array |
LET |
Assign a value to a variable |
OPTION BASE |
Set the starting index of arrays |
SWAP |
Swap two variables |
Function | Description |
---|---|
ASC |
Character to ordinal value |
CHR$ |
Ordinal value to character |
HEX$ |
Integer to hexadecimal string representation |
OCT$ |
Integer to octal string representation |
STR$ |
Numeric value to decimal string representation |
VAL |
String representation to numeric value |
CDBL |
Numeric value to double-precision float |
CINT |
Numeric value to integer |
CSNG |
Numeric value to single-precision float |
CVD |
Byte representation to double-precision float |
CVI |
Byte representation to integer |
CVS |
Byte representation to single-precision float |
MKD$ |
Double-precision float to byte representation |
MKI$ |
Integer to byte representation |
MKS$ |
Single-precision float to byte representation |
Statement | Description |
---|---|
LSET |
Copy a left-justified value into a string buffer |
MID$ |
Copy a value into part of a string buffer |
RSET |
Copy a right-justified value into a string buffer |
Function | Description |
INSTR |
Find |
LEFT$ |
Left substring |
LEN |
String length |
MID$ |
Substring |
RIGHT$ |
Right substring |
SPACE$ |
Repeat spaces |
STRING$ |
Repeat characters |
Statement | Description |
---|---|
CLS |
Clear the screen |
COLOR |
Set colour and palette values |
LOCATE |
Set the position and shape of the text screen cursor |
PALETTE |
Assign a colour to an attribute |
PALETTE USING |
Assign an array of colours to attributes |
PCOPY |
Copy a screen page |
PRINT |
Print expressions to the screen |
VIEW PRINT |
Set the text scrolling region |
WIDTH |
Set the number of text columns on the screen |
Function | Description |
CSRLIN |
Current row of cursor |
POS |
Current column of cursor |
SCREEN |
Character or attribute at given location |
Statement | Description |
---|---|
INPUT |
Retrieve user input on the console |
LINE INPUT |
Retrieve a line of user input on the console |
Function | Description |
INKEY$ |
Nonblocking read from keyboard |
INPUT$ |
Blocking read from keyboard |
Function | Description |
---|---|
ABS |
Absolute value |
ATN |
Arctangent |
COS |
Cosine |
EXP |
Exponential |
FIX |
Truncation |
INT |
Floor |
LOG |
Natural logarithm |
SIN |
Sine |
SGN |
Sign |
SQR |
Square root |
TAN |
Tangent |
Statement | Description |
---|---|
CLOSE |
Close a file |
FIELD |
Assign a string to a random-access record buffer |
GET |
Read a record from a random-access file |
INPUT |
Read a variable from a file |
LINE INPUT |
Read a line from a file |
LOCK |
Locks a file or a range of records against other use |
OPEN |
Open a data file |
PUT |
Write the random-access record buffer to disk |
RESET |
Close all files |
UNLOCK |
Unlocks a file or a range of records against other use |
WIDTH |
Set the number of text columns in a file |
WRITE |
Write expressions to a file |
Function | Description |
EOF |
End of file |
LOC |
Location in file |
LOF |
Length of file |
INPUT$ |
Read a string from a file |
PC-BASIC recognises the following DOS-style devices, which can be used by opening a file on them. Some devices allow specification of further file parameters, such as handshake specifications for serial devices, a filename for cassette devices and a path for disk devices. When operating on disk devices, specifying a path is mandatory.
The filename aliases listed here are only available if the current device is a disk device.
Device | Filename alias | Allowed modes | Description |
---|---|---|---|
SCRN: |
CON |
OUTPUT |
The screen. Output to SCRN: has largely the same
effect as straight output using PRINT .
A difference is the WIDTH setting which is
independent of the real screen width.
|
KYBD: |
CON |
INPUT |
The keyboard. Input read from KYBD: is not echoed
to the screen. Special keys like arrow keys are
registered differently than when using INPUT
or INPUT$ straight.
|
LPT1: LPT2: LPT3: |
PRN for LPT1: |
OUTPUT RANDOM |
Parallel ports 1—3.
LPT devices can be
attached to the physical parallel port, to a printer or to a text file
with the
--lptn options.
Opening a printer for RANDOM has the same effect as opening it
for OUTPUT ; attempting random-file operations will raise
Bad file mode.
|
COM1: COM2: |
AUX for COM1: |
INPUT OUTPUT APPEND RANDOM |
Serial ports 1—2.
COM devices can be attached to a
physical serial port or to a network socket with the
--comn options.
|
CAS1: |
INPUT OUTPUT |
Cassette tape driver. CAS devices can be
attached to a WAV (RIFF Wave) or a CAS (bitmap tape image) file with the --cas1 option.
|
|
A: — Z: and @: |
INPUT OUTPUT APPEND RANDOM |
Disk devices. These devices can be mounted to a directory on
the host file system with the --mount option.
They do not automatically match drive letters on Windows,
unless the --map-drives option
is set.
|
|
NUL |
INPUT OUTPUT APPEND RANDOM |
Null device. This device produces no bytes when opened for INPUT
and absorbs all bytes when opened for OUTPUT .
|
GW-BASIC additionally recognises the following little-used device, which is not implemented in PC-BASIC.
Device | Allowed modes | Description |
---|---|---|
CONS: |
OUTPUT |
The screen (console). Output to CONS: is displayed
directly at the cursor position when Enter is
pressed. It does not update the end-of-line value
for the interpreter, which means that it does not
move with Backspace or Del and is not
stored in program lines if it appears beyond the
end of the existing line. CONS: can be opened with
any access mode, but the effect is always to open
it for OUTPUT .
|
Statement | Description |
---|---|
CIRCLE |
Draw an ellipse or arc section |
DRAW |
Draw a shape defined by a Graphics Macro Language string |
GET |
Store a screen area as a sprite |
LINE |
Draw a line segment |
PAINT |
Flood-fill a connected region |
PSET |
Put a pixel |
PRESET |
Change a pixel to background attribute |
PUT |
Draw a sprite to the screen |
SCREEN |
Change the video mode |
VIEW |
Set the graphics viewport |
WINDOW |
Set logical coordinates |
Function | Description |
POINT |
Graphical pointer coordinates |
POINT |
Pixel attribute |
PMAP |
Convert between physical and logical coordinates |
The SHELL
statement is, by default,
disabled; this is to avoid unpleasant surprises. In GW-BASIC under MS-DOS,
SHELL
opens a DOS prompt or executes commands in it. The command
shells of modern operating systems work differently than those of DOS; in
particular, it is impossible to retrieve changes in the environment variables,
so that many use cases of SHELL
simply would not work; for
example, changing the current drive on Windows. Moreover, Unix shells have a
syntax that is completely different from that of DOS. You can, however, enable
SHELL
by setting the shell=native
option.
Statement | Description |
---|---|
CHDIR |
Change current directory |
FILES |
List the files in the current directory |
KILL |
Delete a file on a disk device |
MKDIR |
Create a new directory |
NAME |
Rename a file on disk |
RMDIR |
Remove a directory |
ENVIRON |
Set a shell environment string |
SHELL |
Enter a DOS shell |
Function | Description |
ENVIRON$ |
String from shell environment table |
Event trapping allows to define subroutines which are executed outside of the normal course of operation. Events that can be trapped are:
ON TIMER
)ON KEY
)ON COM
)ON PLAY
)ON STRIG
)ON PEN
)
Event trapping subroutines are defined as regular subroutines. At the
RETURN
statement, the normal course of
program execution is resumed. Event trapping can be switched on and off or
paused temporarily with statements of the form
PEN ON
, PEN OFF
,
PEN STOP
.
Event trapping only takes place during program execution and is paused while
the program is in an error trap. If an event occurs while event-trapping is
paused, then the event is triggered immediately when event trapping is resumed.
Statement | Description |
---|---|
COM |
Manage serial port event trapping |
KEY |
Manage keyboard event trapping |
KEY |
Define key to trap in keyboard event trapping |
ON |
Define event-trapping subroutine |
PEN |
Manage light pen event trapping |
PLAY |
Manage music queue event trapping |
STRIG |
Manage joystick event trapping |
TIMER |
Manage timer event trapping |
Normally, any error will interrupt program execution and print a message on
the console (exceptions are Overflow and
Division by zero, which print a message but do not interrupt
execution). It is possible to handle errors more graciously by
setting an error-handling routine with the
ON ERROR GOTO line_number
statement. The error-handling routine starts at the given line number
line_number
and continues until a
RESUME
statement is encountered.
Error trapping is in effect both when a program is running and in direct
mode. Error trapping is switched off with the ON ERROR GOTO 0
statement. If an error occurs, or error trapping is switched off, while the
program is executing an error-trapping routine, the program terminates and
an error message is shown.
Only selected memory ranges and selected ports are emulated in PC-BASIC. Some of the most commonly accessed
regions of memory are emulated and can be read and (sometimes) written. There is
read and write support for video memory, font RAM and selected locations of the
low memory segment, including the keyboard buffer. Additionally, there is read
support for font ROM, variable, array and string memory, FIELD
buffers as well as the program code itself. Writing into the program code is
disabled by default, but can be enabled with the allow-code-poke
option. A number of machine ports related to keyboard input and
video modes are supported as well.
Statement | Description |
---|---|
BLOAD |
Load a binary file into memory |
BSAVE |
Save a memory region to file |
CLEAR |
Clears BASIC memory |
DEF SEG |
Set the memory segment |
OUT |
Write a byte to a machine port |
POKE |
Write a byte to a memory location |
WAIT |
Wait for a value on a machine port |
Function | Description |
FRE |
Amount of free memory |
INP |
Byte at machine port |
PEEK |
Byte at memory address |
VARPTR |
Memory address of variable |
VARPTR$ |
Byte representation of length and memory address of variable |
The following language elements are not currently supported in PC-BASIC. The keyword syntax is supported, so no Syntax error should be raised if the statements or functions are used correctly. However, the statements do nothing and the functions return zero or the empty string.
These language elements may be implemented in future versions of PC-BASIC.
GW-BASIC was a real-mode DOS program, which means that it had full control over an IBM-compatible 8086 computer. It had direct access to all areas of memory and all devices. Some BASIC programs used this fact, by using machine-code subroutines to perform tasks for which BASIC did not provide support. PC-BASIC runs on modern machines which may be based on completely different architectures and do not allow applications to access the memory directly. Therefore, it is not possible to run machine code on PC-BASIC. If you need machine code, you'll need to use full CPU emulation such as provided by DOSBox, Bochs or VirtualBox.
Similarly, the IOCTL
functionality depends on an MS-DOS interrupt
and sends a device control string to any DOS device driver. The
syntax of such strings is device-dependent. Since PC-BASIC
emulates neither DOS nor whatever device might be parsing the control string,
it is not possible to use such functionality.
The following language elements are therefore not supported in PC-BASIC. The keyword syntax is supported, so no Syntax error should be raised if the statements or functions are used correctly. However, the statements either do nothing or raise Illegal function call; the functions return zero or the empty string or raise Illegal function call.
Statement | Description | PC-BASIC implementation |
---|---|---|
CALL |
Call a machine code subroutine | Do nothing |
CALLS |
Call a machine code subroutine | Do nothing |
DEF USR |
Define a machine code function | Do nothing |
IOCTL |
Send a device control string to a device | Raise Illegal function call |
Function | Description | PC-BASIC implementation |
IOCTL$ |
Device response to IOCTL |
Raise Illegal function call |
USR |
Machine code function | Return 0 |
This documentation describes the PC-BASIC language, which aims to faithfully emulate GW-BASIC 3.23, IBM Advanced BASIC, IBM Cartridge BASIC and Tandy 1000 GW-BASIC.
Differences with the original languages do arise, and where this is the case they are documented.
Please note that Microsoft's official documentation for the original languages is rather hit-and-miss; it leaves several features undocumented and incorrectly describes others. To avoid making the same errors, the present documentation was written from scratch with reference to the actual behaviour. The errors in this document are therefore all my own. Please contact me if you encounter them.
In descriptions of BASIC syntax, the following conventions apply. Exact rendering of the markup may vary depending on the means used to display this documentation.
bold
italic
[a]
{ a | b }
[ a | b ]
a ...
A program line consists of a line number followed by a compound statement.
Program lines are terminated by a
CR
or
or by the end of the file (optionally through an EOF
character).
Anything on a program line after a NUL
character is ignored.
A line number is a whole number in the range [0—65535]
.
Note that the line numbers 65530—65535
cannot be entered
from the console or a text program file, but can be part of a tokenised program file.
A compound statement consists of statements separated by colons:
statement [: statement] ...
An expression takes one of the following forms:
unary_operator {literal | variable |
array_element | function}
expression binary_operator expression
(expression)
whose elements are described the sections Literals,
Variables, Operators and
Functions.
An array element takes the form
array {[|(} numeric_expression [, numeric_expression ] ... {)|]}
String literals are of the following form:
"[characters]{NUL|CR|EOF|"}
where characters
is a string of characters. Any
character from the current code page can be used, with the following
exceptions, all of which terminate the string literal (aside from other effects they may have):
NUL
(CHR$(&h00)
)CR
(CHR$(&h0D)
)EOF
(CHR$(&h1A)
)"
(CHR$(&h22)
)
Strings are also legally terminated by the end of the file in the absence of
an EOF
character.
Apart from these, string literals should not contain any of the characters
in the ASCII range &h0D
—&h1F
, which lead to unpredictable results.
There is no escaping mechanism. To include one of the above
characters in a string, use string concatenation and
the CHR$
function.
Numeric literals have one of the following forms:
[+|-] [0|1|2|3|4|5|6|7|8|9]...
[.][0|1|2|3|4|5|6|7|8|9]...
[{E|e|D|d}[+|-][0|1|2|3|4|5|6|7|8|9]...]
|#|!|%]
&{H|h}[0|1|2|3|4|5|6|7|8|9|A|B|C|D|E|F|a|b|c|d|e|f]...
&[O|o] [0|1|2|3|4|5|6|7]...
Hexadecimal literals must not contain spaces, but decimal and octal literals may. The o
character in octal literals is optional: they can be
specified equally as &o777
or &777
.
Hexadecimal and octal literals denote integers and do not include a sign. They must range between
[&h0
—&hFFFF
],
of which the range [&h8000
—&hFFFF
]
is interpreted as a two's complement negative integer; for example, &hFFFF = -1
.
Signs can appear left of the &
but these form an expression and are not part of the literal itself.
Floating-point literals must be specified in decimal notation. The decimal separator is the point.
A base-10 exponent may be specified after E
in single-precision floats, or after D
in double-precision floats.
Trailing %
is ignored and does not indicate an integer literal.
Trailing !
or #
mark the literal as single- or double-precision, respectively.
Examples of valid numeric literals are
-1
42
42!
42#
1.3523523
.235435
-.3
3.
.
.e
.D
1.1e+7
1.1d+7
1e2
1e-2
&7
&hffff
&O20
&h
&
65537%
1.1%
Note that expressions such as &o-77
are legal; these are however not
negative octals but rather the expression &o
(empty octal; zero) less 77
(decimal 77).
Variable names must start with a letter; all characters of the variable name
(except the sigil) must be letters A—Z
, figures 0—9
, or a dot .
Only the first 40 characters in the name are significant. A variable name must
not be identical to a reserved word or a reserved word plus sigil.
Therefore, for example, you cannot name a variable TO!
but you can
name it AS!
. Variable names may contain any reserved word.
Variable names may also start with a reserved word, with the exception of USR
and
FN
. Thus, FNORD%
and USRNME$
are not legal variable names while FRECKLE%
and LUSR$
are.
For each name, four different
variables may exist corresponding to the four types. That is, you can have A$
,
A%
, A!
and A#
as different variables.
Which one of those is also known as A
depends on the settings in
DEFINT
/DEFDBL
/DEFSNG
/DEFSTR
.
By default, A
equals the single-precision A!
.
Furthermore, the
arrays A$()
, A%()
,
A!()
, A#()
are separate from the scalar
variables of the same name.
PC-BASIC recognises four variable types, distinguished by their sigil or type character, the last character of the variable's full name:
sigil | type | size | range | precision |
---|---|---|---|---|
$ |
string | 3 bytes plus allocated string space | 0—255 characters | |
% |
integer | 2 bytes | -32768—32767 | exact |
! |
single-precision float | 4 bytes | ±2.938726·10-39—±1.701412·1038 | ~6 significant figures |
# |
double-precision float | 8 bytes | ±2.938735877055719·10-39—±1.701411834604692·1038 | ~16 significant figures |
Note that double-precision floats can hold more decimals than single-precision floats, but not larger or smaller numbers.
While all integers are signed, some statements will interpret negative integers as their two's complement.
Arrays are indexed with round or square
brackets; even mixing brackets is allowed. The following are all legal array elements: A[0]
, A(0)
,
A(0]
, A[0)
. Multidimensional arrays are specified by separating the indices with commas: A(0, 0)
, A[0, 0, 0]
, etc.
By default, arrays are indexed from 0
. This can be changed to
1
using OPTION BASE 1
.
Arrays can be allocated by specifying the largest allowed index using
DIM
. If all indices of the array
are 10
or less, they need not be explicitly allocated. The first
access of the array (read or write) will automatically allocate it with
a maximum index of 10
and the same number of indices as in the first
access. To re-allocate an array, the old array must first be deleted
with CLEAR
or
ERASE
.
PC-BASIC will implicitly convert between the three numerical data types. When a value of one type is assigned to a variable, array element or parameter of another type, it is converted according to the following rules:
The order of precedence of operators is as follows, from tightly bound (high precedence) to loosely bound (low precedence):
^
*
/
\
MOD
+
-
(unary and binary)=
<>
><
<
>
<=
=<
>=
=>
NOT
(unary)AND
OR
XOR
EQV
IMP
Expressions within parentheses ()
are evaluated first.
All binary operators are left-associative: operators of equal precedence are evaluated left to right.
-1^2 = -(1^2) = -1
but (-1)^2 = 1
.
2^3^4 = (2^3)^4 = 4096
.
+
, -
or NOT
is used without a
left operand, Syntax error is raised.
Mathematical operators operate on numeric expressions only.
Note however that +
can take the role of the
string concatenation operator if both
operands are strings.
Code | Operation | Result |
---|---|---|
x ^ y |
Exponentiation |
x raised to the power of
y
|
x * y |
Multiplication |
Product of x and
y
|
x / y |
Division |
Quotient of x and
y
|
x \ y |
Truncated division |
Integer quotient of x and
y
|
x MOD y |
Modulo |
Integer remainder of x by
y (with the sign of x )
|
x + y |
Addition |
Sum of x and y
|
x - y |
Subtraction |
Difference of x and y
|
+ y |
Unary Plus |
Value of y
|
- y |
Negation |
Negative value of y
|
^
will give at most a single-precision result unless the double
option is used.
0^0
will return 1
and not raise an error,
even though, mathematically, raising zero to the zeroeth power is undefined.
+
which will only raise Type mismatch if either but not both operands are strings.
y=0
, x / y
, x MOD y
and
x \ y
will raise Division by zero.
x=0
and y<0
, x^y
will raise Division by zero.
\
or MOD
are not in
[-32768–32767]
, Overflow is raised.
x<0
and y
is a fractional number,
x ^ y
will raise Illegal function call.
Relational operators can operate on numeric as well as string operands; however, if one operand is string and the other numeric, Type mismatch is raised.
Relational operators return either 0
(for false) or
-1
for true.
Code | Operation | Result |
---|---|---|
= |
Equal |
True if a equals b ,
false otherwise.
|
<> >< |
Not equal |
False if a equals b ,
true otherwise.
|
< |
Less than |
True if a is less than b ,
false otherwise.
|
> |
Greater than |
True if a is greater than b ,
false otherwise.
|
<= =< |
Less than or equal |
False if a is greater than b ,
true otherwise.
|
>= => |
Greater than or equal |
False if a is less than b ,
true otherwise.
|
When operating on numeric operands, both operands are compared as floating-point numbers according to the usual ordering of numbers. The equals operator tests for equality to within machine precision for the highest-precision of the two operator types.
When comparing strings, the ordering is as follows.
PC-BASIC has no Boolean type and does not implement Boolean operators. It does, however, implement bitwise operators.
Bitwise operators operate on numeric expressions only. Floating-point operands are rounded to integers before being used.
Code | Operation | Result |
---|---|---|
NOT y |
Complement | -y-1 |
x AND y |
Bitwise conjunction |
The bitwise AND of x and y
|
x OR y |
Bitwise disjunction |
The bitwise OR of x and y
|
x XOR y |
Bitwise exclusive or |
The bitwise XOR of x and y
|
x EQV y |
Bitwise equivalence |
NOT(x XOR y)
|
x IMP y |
Bitwise implication |
NOT(x) OR y
|
These operators can be used
as Boolean operators only if -1
is used to represent true while 0
represents false. Note that PC-BASIC represents
negative integers using the two's complement, so NOT 0 = -1
.
The Boolean interpretation of bitwise operators
is given in the table below.
Code | Operation | Result |
---|---|---|
NOT y |
Logical negation | True if y is false and vice versa |
x AND y |
Conjunction |
Only true if both x and
y are true
|
x OR y |
Disjunction |
Only false if both x and
y are false
|
x XOR y |
Exclusive or |
True if the truth values of x and
y differ
|
x EQV y |
Equivalence |
True if the truth values of x and
y are the same
|
x IMP y |
Implication |
True if x is false or
y is true
|
Be aware that when used on integers other than 0
and -1
,
bitwise operators can not
be interpreted as Boolean operators. For example,
2 AND 1
returns 0
.
[-32768–32767]
, Overflow is raised.
The string concatenation operator is +
. It has a binary as well as a unary form.
The unary minus may also be used on strings, but has no effect.
Code | Operation | Result |
---|---|---|
x + y |
Concatenation | The string formed by x followed by y |
+ y |
Unary Plus |
Value of y
|
- y |
Unary Minus |
Value of y
|
LEN(x) + LEN(y) > 255
, x + y
will raise String too long.
Functions can only be used as part of an expression within a statement; they may take input values
between parentheses and produce a return value. For example,
in PRINT ABS(-1)
the ABS
function is used in an expression within a
PRINT
statement; in Y = SQR(X) + 2
the SQR
function
is used in an expression within a LET
statement.
Some reference works also use terms such as system variable for functions that do not take
an input, presumably since in the GW-BASIC syntax such functions have no parentheses, in contrast to
the languages in the C family (and indeed some modern BASICs).
However, this is simply the GW-BASIC syntax for functions without inputs.
For example, one can do DEF FNA=1: PRINT FNA
in which no parentheses are allowed.
ABS
y = ABS(x)
Returns the absolute value of x
if x
is a number and the
value of x
if x
is a string.
x
is an expression.
ASC
val = ASC(char)
Returns the code point (ASCII value) for the first character of char
.
char
is an expression with
a string value.
char
has a numeric value: Type mismatch.
char
equals ""
: Illegal function call.
ATN
y = ATN(x)
Returns the inverse tangent of x
.
x
is a numeric expression that gives
the angle in radians.
double
option, this function
returns a single-precision value.
ATN(x)
differs in the least significant digit from GW-BASIC.
x
has a string value: Type mismatch.
CDBL
y = CDBL(x)
Converts the numeric expression x
to a double-precision value.
x
has a string value: Type mismatch.
CHR$
char = CHR$(x)
Returns the character with code point x
.
x
is a numeric expression in the range [0—255]
.
x
has a string value: Type mismatch.
x
is not in [-32768—32767]
: Overflow.
x
is not in [0—255]
: Illegal function call.
CINT
y = CINT(x)
Converts the numeric expression x
to a signed integer.
x
has a string value: Type mismatch.
x
is not in [-32768—32767]
: Overflow.
COS
cosine = COS(angle)
Returns the cosine of angle
.
Unless PC-BASIC is run with the double
option,
this function returns a single-precision
value.
angle
is a numeric expression that
gives the angle in radians.
angle
has a string value: Type mismatch.
CSNG
y = CSNG(x)
Converts the numeric expression x
to a single-precision value.
x
has a string value: Type mismatch.
CSRLIN
y = CSRLIN
Returns the screen row of the cursor on the active page.
The return value is in the range [1—25]
.
CVI
y = CVI(s)
Converts a two-byte string to a signed integer.
s
is a string expression that represents an integer using
little-endian two's complement encoding. Only the first two bytes are used.
s
has a numeric value: Type mismatch.
CVS
y = CVS(s)
Converts a four-byte string to a single-precision floating-point number.
s
is a string expression that represents a single-precision
number in Microsoft Binary Format. Only the first four bytes are used.
s
has a numeric value: Type mismatch.
CVD
y = CVD(s)
Converts an eight-byte string to a double-precision floating-point number.
s
is a string expression that represents a double-precision
number in Microsoft Binary Format. Only the first eight bytes are used.
s
has a numeric value: Type mismatch.
DATE$
(function)
s = DATE$
Returns the system date as a string in the format "mm-dd-yyyy"
.
ENVIRON$
value = ENVIRON[ ]$(x)
Returns an environment variable.
x
is an expression.
x
has a string value, returns the value for the environment variable x
or the empty
string if no variable with the name x
is set in the environment table.
x
has a numeric value, it must be in [1—255]
. Returns the x
th entry in
the environment table.
x
is the empty string: Illegal function call.
x
is a number not in [-32768—32767]
: Overflow.
x
is a number not in [1—255]
: Illegal function call.
EOF
is_at_end = EOF(file_num)
Returns -1 if file with number file_num
has reached end-of-file; 0 otherwise.
The file must be open in INPUT
or RANDOM
mode. EOF(0)
returns 0.
file_num
is open to KYBD:
, performs a blocking read and returns -1 if
CTRL+Z is entered, 0 otherwise. The character entered is then echoed to
the console.
file_num
has a string value: Type mismatch.
file_num
is a number not in [-32768—32767]
: Overflow.
file_num
is a number not in [0—255]
: Illegal function call.
file_num
is not 0 or the number of an open file:
Bad file number.
file_num
is in OUTPUT or APPEND mode:
Bad file mode.
ERDEV
zero = ERDEV
Returns 0.
ERDEV$
empty = ERDEV[ ]$
Returns the empty string.
ERL
error_line = ERL
Returns the line number where the last error was raised.
ERR
error_code = ERR
Returns the number of the last error.
EXP
y = EXP(x)
Returns the exponential of x
, i.e. e
to the power x
.
x
is a number-
valued expression.
double
option, this function returns a single-precision
value.
x
, the difference may be 3 digits.
x
has a string value: Type mismatch.
x
is larger than the natural logarithm of the maximum single-precision
value: Overflow.
EXTERR
zero = EXTERR(x)
Returns 0.
x
is a numeric expression in [0—3]
.
x
has a string value: Type mismatch.
x
is not in [-32768—32767]
: Overflow.
x
is not in [0—3]
: Illegal function call.
FIX
whole = FIX(number)
Returns number
truncated towards zero.
number
is a numeric expression.
FIX
truncates towards zero: it removes the fractional part. By contrast, INT
truncates towards negative infinity.
number
is a string expression: Type mismatch.
FN
result = FN[ ]name [(arg_0 [, arg_1] ...)]
Evaluates the user-defined function previously defined with DEF FN name
.
Spaces between FN
and name
are optional.
name
is the name of a previously defined function.
arg_0, arg_1, ...
are expressions, given as parameters to the function.
name
is defined:
Undefined user function.
FRE
free_mem = FRE(x)
Returns the available BASIC memory.
x
is an expression.
x
has a numeric value, it is ignored.
x
has a string value, garbage collection is performed
before returning available memory.
HEX$
hex_repr = HEX$(x)
Returns a string with the hexadecimal representation of x
.
x
is a
numeric expression in [-32768—65535]
. Values for
negative x
are shown as two's-complement.
x
is not in [-32768—65535]
: Overflow.
x
has a string value: Type mismatch.
INKEY$
key = INKEY$
Returns one key-press from the keyboard buffer. If the keyboard buffer is empty, returns the empty string. Otherwise, the return value is a one- or two- character string holding the e-ASCII code of the pressed key.
INKEY$
will return the letters of the associated macro
— unless this macro has been set to empty with the
KEY
statement, in which case
it returns the e-ASCII code for the function key.
INP
code = INP(port)
Returns the value of an emulated machine port.
port
is a numeric expression in [0—65535]
.
port |
Effect | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
&h60 |
Returns the keyboard scancode for the current key pressed or the last key released.
The scancodes returned by INP(&h60) are those
listed in the keyboard scancodes table.
If a key is currently down, the return value is its scancode.
If no key is down, the return value is the scancode of
the last key released, incremented by 128.
|
||||||||||||||||||
&h201 |
Returns the value of the game port (joystick port). This value is
constructed as follows:
OUT &h201, x and then fall back to 0
after a delay. The longer the delay, the higher the axis value.
|
||||||||||||||||||
other values | Returns zero. |
port
is not in [-32768—65535]
: Overflow.
port
has a string value: Type mismatch.
INPUT$
chars = INPUT[ ]$ (num_chars [, [#] file_num])
Returns a string of num_chars
characters from the keyboard or,
if file_num
is provided, from a text file.
num_chars
is a numeric expression in [1—255]
.
file_num
is a numeric expression that returns the number of a text file opened in
INPUT
mode. The #
is optional and has no effect.
INPUT$
. Ctrl+Break and Ctrl+Scroll Lock break
execution whereas Pause halts until another key is pressed (and not read).
KYBD:
, arrow keys, Del,
Home, End, Pg Up, Pg Dn are passed as NUL
characters. Function keys
are ignored if they are event-trapped, otherwise function-key macro replacement is
active as normal.
num_chars
is not in [-32768—32767]
: Overflow.
num_chars
is not in [1—255]
: Illegal function call.
file_num
is not an open file: Bad file number.
file_num
is less than zero: Illegal function call.
file_num
is greater than 32767
: Overflow.
file_num
is not open for INPUT
: Bad file mode.
num_chars
or file_num
are strings: Type mismatch.
file_num
is open to a COM
port and this is the
first INPUT
, LINE INPUT
or INPUT$
call on that port
since the buffer has filled up completely (i.e. LOF(file_num)
has become zero):
Communication buffer overflow.
INSTR
position = INSTR([start,] parent, child)
Returns the location of the first occurrence of the substring child
in
parent
.
parent
and child
are string expressions.
start
is a numeric expression in [1—255]
, specifying
the starting position from where to look; if not specified, the search starts
at character 1.
child
is not a substring of parent
occurring at or before start
,
INSTR
returns 0.
start
has a string value or parent
or child
have numeric values: Type mismatch.
start
is not in [-32768—32767]
: Overflow.
start
is not in [1—255]
: Illegal function call.
INT
whole = INT(number)
Returns number
truncated towards negative infinity.
number
is a numeric expression.
FIX
truncates towards zero: it removes the
fractional part. By contrast, INT
truncates towards negative infinity.
number
is a string expression, Type mismatch .
IOCTL$
result = IOCTL[ ]$ ([#] file_num)
Raises Illegal function call.
IOCTL$
reads the reply to
IOCTL
from a device.
file_num
has a string value: Type mismatch.
file_num
is not in [-32768—32767]
: Overflow.
file_num
is not an open file: Bad file number.
LEFT$
child = LEFT$(parent, num_chars)
Returns the leftmost num_chars
characters of parent
.
parent
is a string expression.
num_chars
is a numeric expression in [0—255]
.
num_chars
is zero or parent
is empty, LEFT$
returns
an empty string.
num_chars
is greater than the length of parent
,
returns parent
.
parent
has a numeric value or num_chars
has a string value: Type mismatch.
num_chars
is not in [-32768—32767]
: Overflow.
num_chars
is not in [0—255]
: Illegal function call.
LEN
length = LEN(string)
Returns the number of characters in string
.
string
is a string
expression.
string
has a number value: Type mismatch.
LOC
location = LOC(file_num)
Returns the current location in the file opened under number file_num
.
INPUT
, OUTPUT
or APPEND
, LOC
returns the number
of 128-byte blocks read or written since opening the file.
RANDOM
, LOC
returns the record number last read or
written.
COM
device, LOC
returns the number of characters
in the input buffer, with a maximum of 255.
KYBD:
, LOC
returns 0.
file_num
is a numeric expression in the range [0—255]
.
file_num
must not be preceded by a #
.
OUTPUT
or APPEND
mode, before any writes LOC
returns 0. After the 128th
character is written, LOC
returns 1.
INPUT
mode, before any reads LOC
returns 1. After the 129th character
is read, LOC
returns 2.
file_num
has a string value: Type mismatch.
file_num
is not in [-32768—32767]
: Overflow.
file_num
is not in [0—255]
: Illegal function call.
file_num
is not an open file: Bad file number.
file_num
is open to a LPT
device: Bad file mode.
LOF
length = LOF(file_num)
Returns the number of bytes in the file open under file_num
.
file_num
is a numeric expression in the range [0—255]
.
file_num
is open to a COM:
device, LOF
returns the number of bytes
free in the input buffer.
file_num
has a string value: Type mismatch.
file_num
is not in [-32768—32767]
: Overflow.
file_num
is not in [0—255]
: Illegal function call.
file_num
is not an open file: Bad file number.
file_num
is open to a LPT
device: Bad file mode.
LOG
y = LOG(x)
Returns the natural logarithm of x
.
x
is a numeric expression greater than zero.
double
option, this function returns a single-precision value.
LOG(x)
can differ from GW-BASIC by 1 in the least significant digit.
x
has a string value: Type mismatch.
x
is zero or negative: Illegal function call.
LPOS
position = LPOS(printer_number)
Returns the column position for a printer.
printer_number
is a numeric expression in [0—3]
.
If it is 0
or 1, the position for LPT1:
is returned. If it is 2, LPT2:
; 3, LPT3:
.
LPT1:
(but not other printers)
is flushed and its position is reset to 1. This is not implemented in
PC-BASIC.
printer_number
has a string value: Type mismatch.
printer_number
is not in [-32768—32767]
: Overflow.
printer_number
is not in [0—3]
: Illegal function call.
MID$
(function)
substring = MID$(string, position [, length])
Returns a substring of string
starting at position
, counting from 1. The
substring has length length
if specified.
If length
is not specified, the substring extends to the end of the string.
string
is a string expression.
position
is a numeric expression between 1 and the string length, inclusive.
length
is a numeric expression in [0—255]
.
string
has a number value or position
or length
have string values: Type mismatch.
position
or length
are not in [-32768—32767]
: Overflow.
position
is not in [1—255]
: Illegal function call.
length
is not in [0—255]
: Illegal function call.
MKD$
bytes = MKD$(double)
Returns the internal 8-byte Microsoft Binary Format representation of a double- precision number.
double
has a string value: Type mismatch.
MKI$
bytes = MKI$(int)
Returns the internal 2-byte little-endian representation of an integer.
int
has a string value: Type mismatch.
int
is not in [-32768—32767]
: Overflow.
MKS$
bytes = MKS$(single)
Returns the internal 8-byte Microsoft Binary Format representation of a single- precision number.
single
has a string value: Type mismatch.
OCT$
octal = OCT$(x)
Returns a string with the octal representation of x
.
x
is a
numeric expression in [-32768—65535]
. Values for
negative x
are shown as two's-complement.
x
has a string value: Type mismatch.
x
is not in [-32768—65535]
: Overflow.
PEEK
value = PEEK(address)
Returns the value of the memory at segment * 16 + address
where segment
is the current segment set with DEF SEG
.
address
is a numeric expression in [-32768—65535]
. Negative values are interpreted as their
two's complement.
PEEK
returns 0.
peek
option. This can be used for compatibility with old
programs. These values will override video or data segment values, if they
are in those locations.
address
has a string value: Type mismatch.
address
is not in [-32768—65535]
: Overflow.
PEN
(function)x = PEN(mode)
Reads the light pen. What this function returns depends on mode
:
mode |
Return value |
---|---|
0 | Boolean; whether the light pen has been down since last poll. |
1 | x coordinate of last pen down position |
2 | y coordinate of last pen down position |
3 | Boolean; whether the pen is currently down |
4 | x coordinate of current pen position |
5 | y coordinate of current pen position |
6 | character row coordinate of last pen down position |
7 | character column coordinate of last pen down position |
8 | character row coordinate of current pen position |
9 | character column coordinate of current pen position |
mode
is a numeric expression in [0—9]
.
mode
has a string value: Type mismatch.
mode
is not in [-32768—32767]
: Overflow.
mode
is not in [0—9]
: Illegal function call.
PLAY
(function)
length = PLAY(voice)
Returns the number of notes in the background music queue. The return value is in [0—16]
.
voice
is a numeric expression in [0—255]
.
If syntax={pcjr|tandy}
, indicates for which tone voice channel
the number of notes is to be returned. If voice
is not in [0—2]
, the
queue for voice 0 is returned.
For other choices of syntax
, the voice
value has no effect.
PLAY
only returns at the
last 16 notes.
voice
has a string value: Type mismatch.
voice
is not in [0—255]
: Illegal function call.
voice
is not in [-32768—32767]
: Overflow.
PMAP
transformed_coord = PMAP(original_coord, fn)
Maps between viewport and logical (WINDOW
) coordinates.
If no VIEW
has been set, the viewport coordinates
are physical coordinates.
Depending on the value of fn
, PMAP
transforms from logical to viewport coordinates or vice versa:
fn |
Return value |
---|---|
0 | return viewport x given logical x |
1 | return viewport y given logical y |
2 | return logical x given viewport x |
3 | return logical y given viewport y |
fn
is a numeric expression in [0—3]
.
PMAP
returns 0.
PMAP
behaves anomalously on SCREEN
changes, where it sometimes
returns results as if the last WINDOW
setting had persisted. This behaviour is not
implemented in PC-BASIC.
[-32768—32767]
: Overflow.
fn
is not in [-32768—32767]
: Overflow.
fn
is not in [0—3]
: Illegal function call.
POINT
(current coordinate)
coord = POINT(fn)
Returns a currently active coordinate of the graphics screen. This is usually
the last position at which a pixel has been plotted, the second corner given
in a LINE
command, or the centre of the viewport if nothing has been plotted.
fn
is a numeric expression in [0—3]
.
The coordinate returned depends on the value of fn
:
fn |
Return value |
---|---|
0 | viewport x |
1 | viewport y |
2 | logical x |
3 | logical y |
fn
is a numeric expression in [0—3]
.
fn
has a string value: Type mismatch.
fn
is not in [-32768—32767]
: Overflow.
fn
is not in [0—3]
: Illegal function call.
POINT
(pixel attribute)
attrib = POINT(x, y)
Returns the attribute of the pixel at logical coordinate x
,y
.
x
, y
are numeric expressions in [-32768—32767]
.
x
,y
is outside the screen, returns -1.
x
or y
has a string value: Type mismatch.
x
or y
or the physical coordinates they translate into are not in
[-32768—32767]
: Overflow.
POS
pos = POS(dummy)
Returns the current cursor column position, in the range [1—80]
.
dummy
is a valid expression of any type; its value has no effect.
RIGHT$
child = RIGHT$(parent, num_chars)
Returns the rightmost num_chars
characters of parent
.
If num_chars
is zero or parent
is empty, RIGHT$
returns
an empty string. If num_chars
is greater than the length of parent
,
returns parent
.
parent
is a string expression.
num_chars
is a numeric expression in [0—255]
.
num_chars
has a string value: Type mismatch.
num_chars
is not in [-32768—32767]
: Overflow.
num_chars
is not in [0—255]
: Illegal function call.
RND
random = RND[(x)]
Returns a pseudorandom number in the interval [0—1)
.
x
is a numeric expression.
x
is zero, RND
repeats the last
pseudo-random number.
x
is greater than zero, a new pseudorandom number is
returned.
x
is negative, x
is converted to a single-precision floating-point value
and the random number seed is set to the absolute value of its mantissa.
The function then generates a new pseudorandom numer with this seed.
Since the only the mantissa of x
is used, any two values whose ratio is a
power of 2 will produce the same seed.
Note that this procedure for generating a new seed differs from that used by RANDOMIZE
.
RND
function generates pseudo-random numbers through a linear congruential generator with modulo 224,
multiplier 214013 and increment 2531011. This exactly reproduces the random numbers of GW-BASIC's RND
.
RND
will wrap around
and start running through the exact same series of numbers all over again. RND
should not be used for
cryptography, scientific simulations or anything else remotely serious.
x
has a string value: Type mismatch.
SCREEN
(function)
value = SCREEN(row, column [, fn])
Returns the code point or colour attribute for the character at position
row
, col
.
row
is a numeric expression in the range [1—25]
.
col
is a numeric expression between 1 and the screen width (40 or 80).
fn
is a numeric expression in [0—255]
. If it is zero or not specified,
the code point of the character is returned. If it is non-zero, in text mode the
attribute is returned; in other screens, 0 is returned.
fn
is not in [0—255]
: Illegal function call.
fn
is not in [-32768—32767]
: Overflow.
row
is not inside the current VIEW PRINT
area:
Illegal function call.
KEY ON
and row=25
: Illegal function call.
col
is not in [1, width]
: Illegal function call.
SGN
sign = SGN(number)
Returns the sign of number
: 1
for positive, 0
for zero and -1
for negative.
number
is a numeric expression.
number
has a string value: Type mismatch.
SIN
sine = SIN(angle)
Returns the sine of angle
.
angle
is a numeric expression giving
the angle in radians.
double
option, this function returns a single-precision value.
angle
has a string value:
Type mismatch.
SPACE$
spaces = SPACE$(number)
Returns a string of number
spaces.
number
is a numeric expression in [0—255]
.
number
has a string value: Type mismatch.
number
is not in [-32768—32767]
: Overflow.
number
is not in [0—255]
: Illegal function call.
SQR
root = SQR(number)
Returns the square root of number
.
number
is a numeric expression.
double
option, this function returns a single-precision value.
number
has a string value: Type mismatch
STICK
pos = STICK(axis)
Returns a coordinate of a joystick axis. All coordinates returned are in the
range [1—254]
with 128
indicating the neutral position.
axis |
Return value |
---|---|
0 | 1st joystick x coordinate |
1 | 1st joystick y coordinate |
2 | 2nd joystick x coordinate |
3 | 2nd joystick y coordinate |
axis
is a numeric expression in [0—3]
and indicates which axis to read.
axis
has a string value: Type mismatch
axis
is not in [-32768—32767]
: Overflow.
axis
is not in [0—3]
: Illegal function call.
STR$
repr = STR$(number)
Returns the string representation of number
.
number
is a numeric expression.
number
has a string value: Type mismatch.
STRIG
(function)
result = STRIG(mode)
Returns the status of the joystick trigger buttons.
STRIG
returns the following
results, all Boolean values:
mode |
Return value |
---|---|
0 | 1st joystick, 1st trigger has been pressed since last poll. |
1 | 1st joystick, 1st trigger is currently pressed. |
2 | 2nd joystick, 1st trigger has been pressed since last poll. |
3 | 2nd joystick, 1st trigger is currently pressed. |
4 | 1st joystick, 2nd trigger has been pressed since last poll. |
5 | 1st joystick, 2nd trigger is currently pressed. |
6 | 2nd joystick, 2nd trigger has been pressed since last poll. |
7 | 2nd joystick, 2nd trigger is currently pressed. |
mode
is a numeric expression in [0—7]
.
STRIG
function returns correct results regardless of the
STRIG ON
status or whether STRIG(0)
has been called first.
mode
has a string value: Type mismatch.
mode
is not in [-32768—32767]
: Overflow.
mode
is not in [0—7]
: Illegal function call.
STRING$
string = STRING$(length, char)
Returns a string of length
times character char
.
char
is a numeric expression, it must be in [0—255]
and is
interpreted as the code point of the character.
char
is a string expression, its first character is used.
length
has a string value: Type mismatch.
char
is the empty string: Illegal function call.
char
or length
is not in [-32768—32767]
: Overflow.
char
or length
is not in [0—255]
: Illegal function call.
TAN
tangent = TAN(angle)
Returns the tangent of angle
.
angle
is a numeric expression giving
the angle in radians.
double
option, this function returns a single-precision value.
angle
close to multiples of π/2
, the tangent is divergent or close
to zero. The values returned will have very low precision in these cases.
angle
has a string value: Type mismatch.
TIME$
(function)
time = TIME$
Returns the current BASIC time in the form "HH:mm:ss"
.
TIMER
(function)
seconds = TIMER
Returns the number of seconds since midnight on the internal BASIC clock.
TIMER
updates in ticks of 1/20 second.
TIMER
are often used as a seed for the
pseudorandom number generator through RANDOMIZE TIMER
. Since these bytes
only take values from a limited set, that's not in fact a particularly good
random seed. However, the pseudorandom number generator included with GW-BASIC and PC-BASIC
is so weak that it should not be used for anything serious anyway.
USR
value = USR[n](expr)
Returns zero.
n
is a digit [0—9]
.
expr
is an expression.
n
is not a digit [0—9]
: Syntax error.
VAL
value = VAL(string)
Returns the numeric value of the string expression string
.
Parsing stops as soon as the first character is encountered that cannot be
part of a number. If no characters are parsed, VAL
returns zero.
See the section on numeric literals for the
recognised number formats.
VAL(" 1 0")
returns 10
.
string
contains one of the ASCII separator
characters CHR$(28)
(file separator),
CHR$(29)
(group separator) or
CHR$(31)
(unit separator),
VAL
returns zero.
This is not the case with CHR$(30)
(record separator).
This behaviour conforms to GW-BASIC.
string
has a number value: Type mismatch.
VARPTR
pointer = VARPTR({name|#file_num})
Returns the memory address of variable name
or of the File Control Block of
file number file_num
.
name
is a
previously defined variable or fully indexed array element.
file_num
is a legal file number.
VARPTR
can be used with PEEK
to read a variable's internal representation.
name
has not been previously defined: Illegal function call.
file_num
has a string value: Type mismatch.
file_num
is not in [1, max_files]
,
where max_files
is the maximum number of files
as set by the max-files
option:
Bad file number.
VARPTR$
pointer = VARPTR$(name)
Returns the memory address of variable name
in the form of a 3-byte string.
The first byte is the length of the record the pointer points to:
The last two bytes are the pointer address (as returned by
VARPTR
) in little-endian order.
name
has not been previously defined: Illegal function call.
A program line is composed of a line number and one or more statements. If multiple statements
are put on one line, they must be separated by colons :
. Statements may be empty.
Each statement has its own idiosyncratic syntax.
Many reference works on GW-BASIC distinguish commands and statements; this distinction stems from the original Dartmouth design of the BASIC language, in which commands were not part of the language and could not be used in programs, but were rather used to control the interpreter itself. However, in GW-BASIC this distinction is less useful and therefore this reference includes what is traditionally thought of as commands in the category of statements.
AUTO
AUTO [line_number|.] [, [increment]]
Start automatic line numbering. Line numbers
are automatically generated when Enter is pressed.
If a program line exists at a generated line number, a *
is shown after the
line number. To avoid overwriting this line, leave it empty and press Enter.
To stop automatic line numbering, press Ctrl+Break or Ctrl+C. The line being edited at
that point is not saved. BASIC will return to command mode, even if AUTO
was
run from a program line.
line_number
, if specified. If .
is specified, line
numbering starts at the last program line that was stored. Otherwise, line
numbering starts at 10
.
increment
, if specified. If a comma
is used without specifying an increment, the last increment specified in an
AUTO
command is used. If not, increment
defaults to 10
.
line_number
is not an unsigned-integer value in [0—65529]
:
Syntax error.
65519
: Undefined line number.
increment
is 0
:
Illegal function call.
BEEP
BEEP
Beep the speaker at 800Hz for 0.25s.
BEEP
(switch)
BEEP {ON|OFF}
This statement has no effect.
syntax={pcjr|tandy}
option.
BEEP OFF
would turn off the internal speaker.
On PC-BASIC, both the internal and the external speaker are emulated through
the same sound system.
BLOAD
BLOAD file_spec [, offset]
Loads a memory image file into memory.
file_spec
is a
valid file specification indicating
the file to read the memory image from.
offset
is a numeric expression in the range [-32768—65535]
.
It indicates an offset in the current DEF SEG
segment where the file is to be
stored. If not specified, the offset stored in the BSAVE
file will be used. If
negative, its two's complement will be used.
BSAVE
format: Bad file mode.
file_spec
contains disallowed characters:
Bad file number (on CAS1:
);
Bad file name (on disk devices).
file_spec
has a numeric value: Type mismatch.
offset
is not in the range [-32768—65535]
: Overflow.
BSAVE
BSAVE file_spec, offset, length
Saves a region of memory to an image file.
file_spec
is a
valid file specification indicating
the file to write to.
offset
is a numeric expression in the range [-32768—65535]
indicating
the offset into the current DEF SEG
segment from where to start reading.
length
is a numeric expression in the range [-32768—65535]
indicating
the number of bytes to read.
offset
or length
are negative, their two's
complement will be used.
file_spec
has a numeric value: Type mismatch.
file_spec
contains disallowed characters:
Bad file number (on CAS1:
);
Bad file name (on disk devices).
offset
is not in the range [-32768—65535]
: Overflow.
length
is not in the range [-32768—65535]
: Overflow.
CALL
CALL address_var [( p0 [, p1] ... )]
Does nothing.
CALL
executes a machine language subroutine.
address_var
is a numeric variable.
p0, p1, ...
are variables.
address_var
is a string variable: Type mismatch.
address_var
is a literal: Syntax error.
CALLS
CALLS address_var [( p0 [, p1] ... )]
Does nothing.
CALLS
executes a FORTRAN subroutine.
address_var
is a numeric variable.
p0, p1, ...
are variables.
address_var
is a string variable: Type mismatch.
address_var
is a literal: Syntax error.
CHAIN
CHAIN [MERGE] file_spec [, [line_number_expr] [, ALL] [, DELETE range [, ign]]]
Loads a program from file into memory and runs it, optionally transferring variables.
ALL
is specified, all variables are transferred. If not, the variables
specified in a COMMON
statement are transferred.
MERGE
is specified, the loaded program is merged into the existing program. To be
able to use this, the program file indicated by file_spec
must be in plain text format.
DELETE
is specified, the range
of line numbers is deleted from the
existing code before the merge. This is pointless without MERGE
.
file_spec
is a
valid file specification indicating
the file to read the program from.
line_number_expr
is a numeric expression. It
will be interpreted as a line number in the new program and execution will
start from this line number. If line_number_expr
is negative, it will be
interpreted as its two's-complement.
range
is a line number range of which the closing line number is
specified and exists before the merge.
ign
is optional and ignored.
CHAIN
preserves the OPTION BASE
setting.
COMMON
variables remain COMMON
for the next CHAIN.
ALL
is specified, DEF FN
definitions are preserved.
MERGE
is specified, DEFINT
, DEFSTR
, DEFSNG
, DEFDBL
definitions
are preserved.
ALL
must precede DELETE
; if unspecified, no comma must
be put in its place and only two commas should precede DELETE
.
file_spec
has a numeric value: Type mismatch.
file_spec
contains disallowed characters:
Bad file number (on CAS1:
);
Bad file name (on disk devices).
file_spec
cannot be found: File not found.
MERGE
is specified and the loaded program was not saved in plain-text mode:
Bad file mode.
range
is greater than 65529: Syntax error.
CHAIN
, no lines are deleted and the new
program is not loaded.
range
does not exist: Illegal function call
line_number_expr
does not evaluate to an existing line number in the
new program, Illegal function call is raised but the load or merge is
being performed.
LF
rather than CR LF
line endings may cause this error.
CHDIR
CHDIR dir_spec
Change the current directory on a disk device to dir_spec
.
Each disk device has its own current directory.
dir_spec
is a
valid file specification indicating an existing
directory on a disk device.
dir_spec
has a numeric value: Type mismatch.
dir_spec
is empty: Bad file name.
CIRCLE
CIRCLE [STEP] (x, y), radius
[, [colour] [, [start] [, [end] [, aspect]]]
Draw an ellipse or ellipse sector.
(x
,y)
.
If STEP
is specified, the midpoint is (x
,y)
away from the current position.
radius
is the radius, in pixels, along the long axis.
colour
is the colour attribute.
start
and end
are specified, a sector of the ellipse is drawn from
start
radians to end
radians, with zero radians the intersection with the
right-hand x axis. If a negative value is specified, the arc sector is
connected by a line to the midpoint.
aspect
specifies the ratio between the y radius and the x radius. If it is
not specified, the standard value for the SCREEN
mode is used (see there), so
as to make the ellipse appear like a circle on the original hardware.
aspect <> 1
, the midpoint algorithm used does not pixel-perfectly
reproduce GW-BASIC's ellipses.
start
or end
is not in [0—2π]
: Illegal function call.
CLEAR
CLEAR [expr] [, [mem_limit] [, [stack_size] [, video_memory]]]
Clears all variables, arrays,DEF FN
user functions, DEFtype
type definitions,
and COMMON
declarations. Closes all files.
Turns off all sound. Resets PLAY
state and sets music to foreground.
Clears all ON ERROR
traps. Resets ERR
and ERL
to zero. Disables all events.
Turns PEN
and STRIG
off. Resets the random number generator.
Clears the loop stack. Resets the DRAW
state and the current graphics position.
mem_limit
specifies the upper limit of usable memory. Default is previous
memory size. Default memory size is 65534.
stack_size
specifies the amount of memory available to the BASIC stack.
Default is previous stack size. Default stack size is 512.
video_memory
specifies the amount of memory available
to the video adapter. This parameter is only legal with one of the options
syntax={pcjr, tandy}
. Instead of using
CLEAR
, the option video-memory
can also be used to set video memory size.
expr
is unknown.
FOR
—NEXT
or
WHILE
—WEND
loop, an error will be raised at
the NEXT
or WEND
statement, since the loop stacks have been cleared.
mem_limit
, stack_size
are not in [-32768—65535]
: Overflow.
mem_limit
or stack_size
equal 0
: Illegal function call.
mem_limit
equals -1
or 65535
: Out of memory.
mem_limit
or expr
are too low: Out of memory.
expr
is not in [-32768—32767]
: Overflow.
expr
is negative: Illegal function call.
CLOSE
CLOSE [[#] file_0 [, [#] file_1] ...]
Closes files. If no file numbers are specified, all open files are closed.
The hash (#
) is optional and has no effect.
file_1, file_2, ...
are numeric expressions yielding
file numbers.
file_1, file_2, ...
are not in [-32768—32767]
: Overflow.
file_1, file_2, ...
are not in [0—255]
: Illegal function call.
file_1, file_2, ...
have a string value: Type mismatch.
CLS
CLS [x][,]
Clears the screen or part of it.
If x
is not specified, in SCREEN 0 the text view region is cleared;
in other screens, the graphics view region is cleared.
The comma is optional and has no effect.
x
is a numeric valued expression that determines what is cleared:
x = 0
, the whole screen is cleared.
x = 1
, the graphics view region is cleared.
x = 2
, the text view region is cleared.
x
is has a string value: Type mismatch.
x
is not in [-32768—32767]
: Overflow .
x
is not in [0, 1, 2]
: Illegal function call.
COLOR
(text mode)
COLOR [foreground] [, [background] [, border]]
Changes the current foreground and background attributes. All new characters printed will take the newly set attributes. Existing characters on the screen are not affected.
foreground
is a numeric expression in [0—31]
.
This specifies the new foreground attribute. Attributes 16—31
are
blinking versions of attributes 0—15
.
background
is a numeric expression in [0—15]
.
This specifies the new background attribute. It is taken MOD 8
: Values
8—15
produce the same colour as 0—7
.
border
is a numeric expression in [0—15]
specifying the border attribute.
Background attribute | |||||||||
---|---|---|---|---|---|---|---|---|---|
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | ||
FG | 0 | 00 XX | 10 XX | 20 XX | 30 XX | 40 XX | 50 XX | 60 XX | 70 XX |
1 | 01 XX | 11 XX | 21 XX | 31 XX | 41 XX | 51 XX | 61 XX | 71 XX | |
2 | 02 XX | 12 XX | 22 XX | 32 XX | 42 XX | 52 XX | 62 XX | 72 XX | |
3 | 03 XX | 13 XX | 23 XX | 33 XX | 43 XX | 53 XX | 63 XX | 73 XX | |
4 | 04 XX | 14 XX | 24 XX | 34 XX | 44 XX | 54 XX | 64 XX | 74 XX | |
5 | 05 XX | 15 XX | 25 XX | 35 XX | 45 XX | 55 XX | 65 XX | 75 XX | |
6 | 06 XX | 16 XX | 26 XX | 36 XX | 46 XX | 56 XX | 66 XX | 76 XX | |
7 | 07 XX | 17 XX | 27 XX | 37 XX | 47 XX | 57 XX | 67 XX | 77 XX | |
8 | 08 XX | 18 XX | 28 XX | 38 XX | 48 XX | 58 XX | 68 XX | 78 XX | |
9 | 09 XX | 19 XX | 29 XX | 39 XX | 49 XX | 59 XX | 69 XX | 79 XX | |
10 | 0a XX | 1a XX | 2a XX | 3a XX | 4a XX | 5a XX | 6a XX | 7a XX | |
11 | 0b XX | 1b XX | 2b XX | 3b XX | 4b XX | 5b XX | 6b XX | 7b XX | |
12 | 0c XX | 1c XX | 2c XX | 3c XX | 4c XX | 5c XX | 6c XX | 7c XX | |
13 | 0d XX | 1d XX | 2d XX | 3d XX | 4d XX | 5d XX | 6d XX | 7d XX | |
14 | 0e XX | 1e XX | 2e XX | 3e XX | 4e XX | 5e XX | 6e XX | 7e XX | |
15 | 0f XX | 1f XX | 2f XX | 3f XX | 4f XX | 5f XX | 6f XX | 7f XX | |
16 | 80 XX | 90 XX | a0 XX | b0 XX | c0 XX | d0 XX | e0 XX | f0 XX | |
17 | 81 XX | 91 XX | a1 XX | b1 XX | c1 XX | d1 XX | e1 XX | f1 XX | |
18 | 82 XX | 92 XX | a2 XX | b2 XX | c2 XX | d2 XX | e2 XX | f2 XX | |
19 | 83 XX | 93 XX | a3 XX | b3 XX | c3 XX | d3 XX | e3 XX | f3 XX | |
20 | 84 XX | 94 XX | a4 XX | b4 XX | c4 XX | d4 XX | e4 XX | f4 XX | |
21 | 85 XX | 95 XX | a5 XX | b5 XX | c5 XX | d5 XX | e5 XX | f5 XX | |
22 | 86 XX | 96 XX | a6 XX | b6 XX | c6 XX | d6 XX | e6 XX | f6 XX | |
23 | 87 XX | 97 XX | a7 XX | b7 XX | c7 XX | d7 XX | e7 XX | f7 XX | |
24 | 88 XX | 98 XX | a8 XX | b8 XX | c8 XX | d8 XX | e8 XX | f8 XX | |
25 | 89 XX | 99 XX | a9 XX | b9 XX | c9 XX | d9 XX | e9 XX | f9 XX | |
26 | 8a XX | 9a XX | aa XX | ba XX | ca XX | da XX | ea XX | fa XX | |
27 | 8b XX | 9b XX | ab XX | bb XX | cb XX | db XX | eb XX | fb XX | |
28 | 8c XX | 9c XX | ac XX | bc XX | cc XX | dc XX | ec XX | fc XX | |
29 | 8d XX | 9d XX | ad XX | bd XX | cd XX | dd XX | ed XX | fd XX | |
30 | 8e XX | 9e XX | ae XX | be XX | ce XX | de XX | ee XX | fe XX | |
31 | 8f XX | 9f XX | af XX | bf XX | cf XX | df XX | ef XX | ff XX |
Background attribute | |||||||||
---|---|---|---|---|---|---|---|---|---|
0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | ||
FG | 0 | 00 XX | 10 XX | 20 XX | 30 XX | 40 XX | 50 XX | 60 XX | 70 XX |
1 | 01 XX | 11 XX | 21 XX | 31 XX | 41 XX | 51 XX | 61 XX | 71 XX | |
2 | 02 XX | 12 XX | 22 XX | 32 XX | 42 XX | 52 XX | 62 XX | 72 XX | |
3 | 03 XX | 13 XX | 23 XX | 33 XX | 43 XX | 53 XX | 63 XX | 73 XX | |
4 | 04 XX | 14 XX | 24 XX | 34 XX | 44 XX | 54 XX | 64 XX | 74 XX | |
5 | 05 XX | 15 XX | 25 XX | 35 XX | 45 XX | 55 XX | 65 XX | 75 XX | |
6 | 06 XX | 16 XX | 26 XX | 36 XX | 46 XX | 56 XX | 66 XX | 76 XX | |
7 | 07 XX | 17 XX | 27 XX | 37 XX | 47 XX | 57 XX | 67 XX | 77 XX | |
8 | 08 XX | 18 XX | 28 XX | 38 XX | 48 XX | 58 XX | 68 XX | 78 XX | |
9 | 09 XX | 19 XX | 29 XX | 39 XX | 49 XX | 59 XX | 69 XX | 79 XX | |
10 | 0a XX | 1a XX | 2a XX | 3a XX | 4a XX | 5a XX | 6a XX | 7a XX | |
11 | 0b XX | 1b XX | 2b XX | 3b XX | 4b XX | 5b XX | 6b XX | 7b XX | |
12 | 0c XX | 1c XX | 2c XX | 3c XX | 4c XX | 5c XX | 6c XX | 7c XX | |
13 | 0d XX | 1d XX | 2d XX | 3d XX | 4d XX | 5d XX | 6d XX | 7d XX | |
14 | 0e XX | 1e XX | 2e XX | 3e XX | 4e XX | 5e XX | 6e XX | 7e XX | |
15 | 0f XX | 1f XX | 2f XX | 3f XX | 4f XX | 5f XX | 6f XX | 7f XX | |
16 | 80 XX | 90 XX | a0 XX | b0 XX | c0 XX | d0 XX | e0 XX | f0 XX | |
17 | 81 XX | 91 XX | a1 XX | b1 XX | c1 XX | d1 XX | e1 XX | f1 XX | |
18 | 82 XX | 92 XX | a2 XX | b2 XX | c2 XX | d2 XX | e2 XX | f2 XX | |
19 | 83 XX | 93 XX | a3 XX | b3 XX | c3 XX | d3 XX | e3 XX | f3 XX | |
20 | 84 XX | 94 XX | a4 XX | b4 XX | c4 XX | d4 XX | e4 XX | f4 XX | |
21 | 85 XX | 95 XX | a5 XX | b5 XX | c5 XX | d5 XX | e5 XX | f5 XX | |
22 | 86 XX | 96 XX | a6 XX | b6 XX | c6 XX | d6 XX | e6 XX | f6 XX | |
23 | 87 XX | 97 XX | a7 XX | b7 XX | c7 XX | d7 XX | e7 XX | f7 XX | |
24 | 88 XX | 98 XX | a8 XX | b8 XX | c8 XX | d8 XX | e8 XX | f8 XX | |
25 | 89 XX | 99 XX | a9 XX | b9 XX | c9 XX | d9 XX | e9 XX | f9 XX | |
26 | 8a XX | 9a XX | aa XX | ba XX | ca XX | da XX | ea XX | fa XX | |
27 | 8b XX | 9b XX | ab XX | bb XX | cb XX | db XX | eb XX | fb XX | |
28 | 8c XX | 9c XX | ac XX | bc XX | cc XX | dc XX | ec XX | fc XX | |
29 | 8d XX | 9d XX | ad XX | bd XX | cd XX | dd XX | ed XX | fd XX | |
30 | 8e XX | 9e XX | ae XX | be XX | ce XX | de XX | ee XX | fe XX | |
31 | 8f XX | 9f XX | af XX | bf XX | cf XX | df XX | ef XX | ff XX |
COLOR
is different in different SCREEN
modes: COLOR
(text mode),
COLOR
(SCREEN 1
),
(SCREEN 3—9
).
[-32768—32767]
: Overflow.
foreground
is not in [0—31]
, background
is not in
[0—15]
or border
is not in [0—15]
: Illegal function call.
SCREEN 2
: Illegal function call.
COLOR
(SCREEN 1
)
COLOR [palette_0] [, palette [, override]]
Assigns new colours to the palette of attributes.
palette_0
is a numeric expression in [0—255]
.
This sets the palette colour associated with attribute 0; by default, the
background has this attribute. All pixels with this attribute will
change colour. The palette colour value is taken from the 64-colour
set. palette_0
is taken MOD 64
.
palette
is a numeric expression in [0—255]
that specifies the palette:
palette
odd sets the standard CGA palette (cyan, magenta, grey).
palette
even sets the alternative palette (green, red, brown).
override
is a numeric expression in [0—255]
.
If override
is specified, palette is set as above but using override
instead of palette
. palette
is then ignored.
Attribute | Palette 0 | Palette 1 | Alternate palette | ||||||
---|---|---|---|---|---|---|---|---|---|
Colour | Lo | Hi | Colour | Lo | Hi | Colour | Lo | Hi | |
0 | Black | Black | Black | ||||||
1 | Green | Cyan | Cyan | ||||||
2 | Red | Magenta | Red | ||||||
3 | Brown | White | White |
COLOR
is different in different SCREEN
modes: COLOR
(text mode),
COLOR
(SCREEN 1
),
(SCREEN 3—9
).
[-32768—32767]
: Overflow.
[0—255]
: Illegal function call.
COLOR
(SCREEN 3—9
)
COLOR [foreground] [, palette_0 [, dummy]]
Changes the current foreground attribute and the colour for attribute 0.
foreground
is a numeric expression in [0—15]
This sets the new foreground attribute. This applies only to new characters
printed or pixels plotted.
palette_0
is a numeric expression in [0—15]
This sets the colour associated with attribute 0; by default, the
background has this attribute. All pixels with this attribute will
change colour.
In SCREEN 7
and 8
, the palette_0
colour is taken from the first 8 of
the 16-colour EGA set. palette_0
is taken MOD 8
.
IN SCREEN 9
, the colour value is taken from the 64-colour set.
dummy
is a numeric expression with a value in [0—255]
The value of dummy
is ignored.
Attribute | Colour | |
---|---|---|
0 | Black | |
1 | Blue | |
2 | Green | |
3 | Cyan | |
4 | Red | |
5 | Magenta | |
6 | Brown | |
7 | Low-intensity white | |
8 | Grey | |
9 | Light Blue | |
10 | Light Green | |
11 | Light Cyan | |
12 | Light Red | |
13 | Light Magenta | |
14 | Light Yellow | |
15 | High-intensity white |
0 | 8 | 16 | 24 | 32 | 40 | 48 | 56 | ||||||||
1 | 9 | 17 | 25 | 33 | 41 | 49 | 57 | ||||||||
2 | 10 | 18 | 26 | 34 | 42 | 50 | 58 | ||||||||
3 | 11 | 19 | 27 | 35 | 43 | 51 | 59 | ||||||||
4 | 12 | 20 | 28 | 36 | 44 | 52 | 60 | ||||||||
5 | 13 | 21 | 29 | 37 | 45 | 53 | 61 | ||||||||
6 | 14 | 22 | 30 | 38 | 46 | 54 | 62 | ||||||||
7 | 15 | 23 | 31 | 39 | 47 | 55 | 63 |
COLOR
is different in different SCREEN
modes: COLOR
(text mode),
COLOR
(SCREEN 1
),
(SCREEN 3—9
).
[-32768—32767]
: Overflow.
foreground
is not in [1—15]
; background
is not in [0—15]
; or
dummy
is not in [0—255]
: Illegal function call.
COM
COM(port) {ON|OFF|STOP}
ON
: enables ON COM(port)
event trapping of the emulated serial port.
OFF
: disables trapping.
STOP
: halts trapping until COM(port) ON
is used. Events that occur
while trapping is halted will trigger immediately when trapping is re-enabled.
port
is a numeric expression with a value of 1
or 2
. This specifies which
serial port (COM1:
or COM2:
) is trapped.
COMMON
COMMON [var_0 [, [var_1]] ...]
Specifies variables to be passed as common variables to the program called
with CHAIN
.
The statement may end with one or more commas.
var_0, var_1, ...
are names of variables or arrays. Array names
must be followed by parentheses or square brackets. Brackets may also be mixed: a(]
b[)
.
CONT
CONT [anything]
Resumes execution of a program that has been halted by
STOP
, END
,
Ctrl+C, or Ctrl+Break.
CONT
keyword is ignored.
GOSUB
routine called from a continuing
direct line (e.g. GOSUB 100:PRINT A$
), CONT
will overwrite the running
direct line. As the subroutine RETURN
s to the position after the GOSUB
in
the old direct line, strange things may happen if commands are given after
CONT
. In GW-BASIC, this can lead to strange errors in non-existing
program lines as the parser executes bytes that are not part of a program
line. In PC-BASIC, if the new direct line is shorter, execution stops
after RETURN
; but if the direct line is extended beyond the old return
position, the parser tries to resume at that return position, with strange
effects.
CLEAR
: Can't continue.
CONT
is used in a program: Can't continue.
DATA
DATA [const_0] [, [const_1]] ...
Specifies data that can be read by a READ
statement.
const_0, const_1, ...
are string and number literals or may be empty. String literals can be given
with or without quotation marks. If quotation marks are omitted, leading and
trailing whitespace is ignored and commas or colons will terminate the data
statement.
READ
statement, a Syntax error occurs on the DATA
statement.
DATE$
(statement)
DATE$ = date
Sets the system date. date
is a string expression that represents a
date in one of the formats: "mm-dd-yyyy"
, "mm/dd/yyyy"
, "mm-dd-yy"
, "mm/dd/yy"
.
Of these,
mm
must be in [01—12]
.
dd
must be in [01—31]
.
yyyy
must be in [1980—2099]
.
yy
must be in one of the ranges:
[00—77]
, interpreted as 2000—2077
; or
[80—99]
, interpreted as 1980—1999
.
"02-31-2000"
. PC-BASIC
raises Illegal function call for these.
date
has a numeric value: Type mismatch.
date
is not in the format specified above:
Illegal function call.
DEF FN
DEF FN[ ]name [(arg_0 [, arg_1] ...)] = expression
Defines a function called FNname
(or FN name
: spaces between FN
and name
are optional).
On calling FNname( ... )
, expression
is
evaluated with the supplied parameters substituted. Any variable names used in the function that are not
in the argument list refer to the corresponding global variables.
The result of the
evaluation is the return value of FNname
. The type of the return value
must be compatible with the type indicated by name
.
name
must be a legal variable name.
arg_0, arg_1, ...
must be legal variable names. These are the parameters of the
function. Variables of the same name may or may not exist in the program; their value is not affected or used by the defined function.
expression
must be a legal PC-BASIC expression.
name
,
no error is raised at the DEF FN
statement; however, a Type mismatch
will be raised at the first call of FNname
.
DEFINT
, DEFDBL
, DEFSNG
, DEFSTR
{DEFINT|DEFDBL|DEFSNG|DEFSTR} first_0[- last_0] [, first_1[- last_1]] ...
Sets the type that is assumed if no sigil is specified when a variable name is used. The statement sets the default type for variables starting with a letter from the ranges specified.
The default type is set to:
DEFINT
%
)DEFDBL
#
)DEFSNG
!
)DEFSTR
$
)first_0, last_0, ...
are letters of the alphabet.
Pairs of letters connected by a dash -
indicate inclusive ranges.
DEFSNG A-Z
is the default setting.
DEF SEG
DEF SEG [= address]
Sets the memory segment to be used by BLOAD
, BSAVE
, CALL
,
PEEK
, POKE
, and USR
.
address
is a numeric expression in [-32768—65535]
.
address
is negative, it is interpreted as its two's complement.
address
is not specified, the segment is set to the GW-BASIC data
segment.
address
has a string value: Type mismatch.
address
is not in [-32768—65535]
: Overflow.
DEF USR
DEF USR[n] = address
Does nothing.
n
is a digit between 0 and 9 inclusive.
address
is a numeric expression in [-32768—65535]
.
address
is negative, it is interpreted as its two's complement.
n
is not a digit in [0—9]
: Syntax error.
address
has a string value: Type mismatch.
address
is not in [-32768—65535]
: Overflow.
DELETE
DELETE [line_number_0|.] [-[line_number_1|.] ]
Deletes a range of lines from the program. Also stops program execution and returns control to the user.
line_number_0
and
line_number_1
are line numbers in the range [0—65529]
, specifying the inclusive range of line numbers to delete.
.
indicates the last line edited.
line_number_0
or
line_number_1
is greater than 65529
: Syntax error.
DIM
DIM name {(|[} limit_0 [, limit_1] ... {)|]}
Allocates memory for arrays.
The DIM
statement also fixes the number of indices of the array.
An array can only be allocated once; to re-allocate an array, ERASE
or
CLEAR
must be executed first.
If an array is first used without a DIM
statement, it is automatically allocated with its maximum indices set at 10
for each index position used. If an array's DIM
statement specifies no indices,
it is allocated with a single index with maximum 10
.
The least index allowed is determined by OPTION BASE
.
name
is a legal variable name
specifying the array to be allocated.
limit_0, limit_1, ...
are numeric
expressions that specify the greatest index allowed at that position.
255
. In practice,
it is limited by the 255-byte limit on the length of program lines.
name
has already been dimensioned: Duplicate definition.
limit_0, limit_1, ...
have a string value: Type mismatch.
limit_0, limit_1, ...
are not within [-32768—32767]
: Overflow.
limit_0, limit_1, ...
are negative: Illegal function call.
DRAW
DRAW gml_string
Draws the shape specified by gml_string
,
a string expression in Graphics Macro Language (GML).
[B][N] movement
where the default is to move and draw; the optional prefixes mean:
B |
move but do not plot |
N |
return to original point after move |
movement
is one of:
U[n] |
up n steps |
L[n] |
left n steps |
D[n] |
down n steps |
R[n] |
right n steps |
E[n] |
up and right n steps |
F[n] |
down and right n steps |
G[n] |
down and left n steps |
H[n] |
up and left n steps |
M{+|-}x,[+|-]y |
move (x ,y ) steps |
Mx,y |
move to view region coordinate (x ,y ) |
where n
is an integer in [-32768—32767]
and
x
, y
are integers in [0—9999]
.
Where optional, n
defaults to 1
.
Sn |
set the step size to n/4 . The default step size is 1 pixel.
n is an integer in [1—255]
|
TAn |
set the angle to n degrees. The default angle is 0 degrees.
n is an integer in [-360—360]
|
An |
set the angle to
0 for n=0 ,
90 for n=1 ,
180 for n=2 ,
270 for n=3 .
n is an integer in [0—3]
|
Xs |
execute a substring |
s
is one of the following:
;
)VARPTR$()
on a string variable
Numeric variables n
, x
,
y
, b
in the commands above can be:
DRAW "U100"
var
preceded by =
and followed by ;
.
For example, DRAW "U=VAR;"
or DRAW "U=A(1);"
VARPTR$(var)
preceded by =
. For example, DRAW "U=" + VARPTR$(VAR)
CLS
statement resets the step size to 1 pixel, angle to 0 degrees and position to the
centre of the view region.
n
in the TA
, A
and C
command can be left out but only if the
command is terminated by a semicolon. n
defaults to 0
.
U
, L
, D
,
R
, E
, F
, G
, H
, and C
can be in the range [-99999—99999]
;
however, results for large numbers are unpredictable. This is not implemented in PC-BASIC.
gml_string
has a numeric value: Type mismatch.
gml_string
has errors in the GML: Illegal function call.
EDIT
EDIT {line_number|.}
Displays the specified program line with the cursor positioned for editing.
line_number
must be a line that exists in the program, or a period (.) to
indicate the last line stored.
line_number
is not in [0—65529]
: Illegal function call.
ELSE
ELSE [anything]
Unless part of an IF
statement on the same line, anything after ELSE
is ignored
in the same way as after '
or :REM
. No colon :
preceding
the ELSE
statement is necessary. See IF
for normal usage.
END
END
Closes all files, stops program execution and returns control to the user.
No message is printed. It is possible to resume execution at the next statement
using CONT
.
ENVIRON
ENVIRON command_string
Sets a shell environment variable.
command_string
is a string expression of one of the following forms:
"VARIABLE=VALUE"
VARIABLE
to VALUE
;
"VARIABLE="
VARIABLE
.
command_string
has a numeric value: Type mismatch.
command_string
is not of the required form: Illegal function call.
ERASE
ERASE array_0 [, array_1] ...
De-allocates arrays. The data stored in the arrays is lost.
array_0, array_1 ...
are names of existing arrays. The names must be
specified without brackets.
array_0, array_1 ...
do not exist: Illegal function call.
ERROR
ERROR error_number
Raises the error with number error_number
.
error_number
is an expression
with a numeric value.
error_number
has a string value: Type mismatch.
error_number
is not in [-32768—32767]
: Overflow.
error_number
is not in [1—255]
: Illegal function call.
FIELD
FIELD [#] file_number [, width_0 AS name_0 [, width_1 AS name_1] ...]
Assigns variables to the random-access record buffer. The record buffer is a
region of memory of length defined by the OPEN
statement; the default record
length is 128 bytes. The FIELD
statement assigns a portion of this region to
one or more fixed-length string variables, so that the value of these strings
is whatever happens to be in the record buffer at that location.
FIELD
statement
without any variables specified has no effect.
FIELD
statement on the same file will specify an alternative mapping of the
same file buffer; all mappings will be in effect simultaneously.
LET
or MID$
statement on name_0 , name_1 ...
will dis-
associate the string variable from the field buffer.
LSET
, RSET
or
MID$
to copy values into a FIELD
buffer.
GET
to read values from the file into the field
buffer, changing the variables.
PUT
to write the field buffer to the file.
file_number
is a numeric expression that yields the number of an open random-access file. The #
is optional and has no effect.
width_0, width_1, ...
are numeric
expressions giving the length of the string variables
name_0 , name_1 ...
are string variables.
file_number
is not in [0—255]
: Illegal function call.
file_number
is not the number of an open file:
Bad file number.
file_number
is open under a mode other than RANDOM
:
Bad file mode.
FIELD
statement add up to a number larger than the
record length of the field buffer: Field overflow.
name_0 , name_1 ...
specify a non-string variable: Type mismatch.
FILES
FILES [filter_spec]
Displays the files fitting the specified filter in the specified directory on a disk device. If
filter_spec
is not specified, displays all files in the current working
directory.
filter_spec
is a string expression that
is much like a file specification, but optionally allows the file
name part to contain wildcards.
? |
Matches any legal file name character. |
* |
Matches any series of legal file name characters. |
\
or extension separators .
. To match all files with all extensions,
use *.*
.
\
.
filter_spec
has a numeric value: Type mismatch.
filter_spec
is the empty string: Bad file name.
FOR
FOR loop_var = start TO stop [STEP step]
Initiates a FOR—NEXT
loop.
Initially, loop_var
is set to start
. Then, the statements between the FOR
statement and the NEXT
statement are executed and loop_var
is incremented by
step
(if step
is not specified, by 1). This is repeated until loop_var
has become greater than stop
. Execution then continues at the statement
following NEXT
. The value of loop_var
equals stop+step
after the loop.
loop_var
is a numeric variable.
start
, stop
and step
are numeric expressions.
NEXT
statement is found to match the FOR
statement: FOR without NEXT occurs at the FOR
statement.
loop_var
is a string variable or start
,
stop
, or end
has a string value:
Type mismatch.
loop_var
is an array element: Syntax error .
loop_var
is an integer variable and a start
, stop
or step
is outside the range [-32768, 32767]
: Overflow .
GET
(files)
GET [#] file_number [, record_number]
Read a record from the random-access file file_number
at position
record_number
.
The record can be accessed through the FIELD
variables or through INPUT$
,
INPUT
or
LINE INPUT
.
file_number
is a numeric expression that yields the number
of an open random-access file. The #
is optional and has no effect.
record_number
is a numeric expression in [1—33554432]
(2^25
), and is interpreted as the record number.
2^25
.
record_number
is not in [1—33554432]
: Bad record number.
file_number
is not in [0—255]
: Illegal function call.
file_number
is not the number of an open file:
Bad file number.
file_number
is open under a mode other than RANDOM
:
Bad file mode.
file_number
is not specified: Missing operand.
GET
(communications)
GET [#] com_file_number [, number_bytes]
Read number_bytes
bytes from the communications buffer opened under file
number com_file_number
.
The record can be accessed through the FIELD
variables or through INPUT$
,
INPUT
or
LINE INPUT
.
file_number
is a numeric expression that yields the number
of a file open to a COM
device. The #
is optional and has no effect.
number_bytes
is a numeric expression between 1
and the COM
buffer length, inclusive.
bytes
is 32768
or greater, GW-BASIC hangs. This functionality is not implemented in PC-BASIC.
bytes
is less than 1: Bad record number
bytes
is less than 32768
and greater than the COM
buffer length: Illegal function call.
com_file_number
is not specified: Missing operand.
com_file_number
is not in [0—255]
: Illegal function call.
com_file_number
is not the number of an open file:
Bad file number.
LOF(com_file_number) = 0
, and
LOC(com_file_number) = 255
: Communication buffer overflow
GET
, hangs until the Ctrl+Break key is pressed.
GET
(graphics)
GET (x0, y0) - [STEP] (x1, y1), array_name
Stores a rectangular area of the graphics screen in an array.
The area stored is a rectangle parallel to the screen edges, bounded by the
top-left and bottom-right coordinates x0
,y0
and x1
,y1
. If STEP
is
specified, x1
,y1
is an offset from x0
,y0
. The area is such that these
corner points are inside it.
The image stored in the array can then be put on the screen using PUT. For the
purposes of GET
, any array is considered a string of bytes. The byte size of an
array can be calculated as number_elements * byte_size
with byte_size
equal to
2
for integers (%
), 4 for single (!
) and 8 for double (#
).
Array byte size for
string is 3, but string arrays are not allowed in GET
. For calculating the
number of elements, keep in mind that OPTION BASE 0
is the default; in which
case an array with maximum index 10 has 11 elements. This works through in
multidimensional arrays.
The array format is as follows:
Byte | Contains |
---|---|
0, 1 | Number of x pixels, unsigned int. In SCREEN 1 , this value is doubled. |
2, 3 | Number of y pixels, unsigned int. |
4— |
Pixel data. Data is arranged in 2-byte words. The first 16-bit word holds the bit 0 of
the first 16 pixels on the top row. The second word holds the second bit,
etc. Data is word-aligned at the end of each row. Thus, in a screen mode
with 4 bits per pixel, the first row takes at least 8 bytes (4 words), even
if it consists of only one pixel. The number of bits per pixel depends on
the SCREEN mode.
|
array_name
is the name of a numeric array dimensioned with enough space to store the area.
x0
, y0
, x1
, y1
are numeric expressions.
SCREEN 6
, GET
stores an area of twice the width
of the specified rectangle.
array_name
refers to a string array: Type mismatch.
x0
, ... y1
are string expressions: Type mismatch.
x0
, ... y1
are not in [-32768—32767]
: Overflow.
x0
, ... y1
are outside the current VIEW
or WINDOW
:
Illegal function call
GOSUB
GO[ ]SUB line_number [anything]
Jumps to a subroutine at line_number
. The next
RETURN
statement jumps back to
the statement after GOSUB
. Anything after line_number
until the end of the
statement is ignored. If executed from a direct line, GOSUB
runs the subroutine and
the following RETURN
returns execution to the direct line.
line_number
is an existing line number literal.
RETURN
is encountered, no problem.
GO
and SUB
; it will not be retained in
the program.
line_number
does not exist: Undefined line number.
line_number
is greater than 65529
, only the first 4 characters are
read (e.g. 6553
)
GOTO
GO[ ]TO line_number [anything]
Jumps to line_number
. Anything after line_number
until the end of the
statement is ignored. If executed from a direct line, GOTO
starts execution of the program at the specified line.
line_number
is an existing line number literal.
GO
and TO
, but they will
not be retained in the program.
line_number
is greater than 65529
, only the first 4 characters are
read (e.g. GOTO 65530
is executed as GOTO 6553
)
line_number
does not exist: Undefined line number.
IF
IF truth_value [,] {THEN|GOTO} [compound_statement_true|line_number_true [anything]]
[ELSE [compound_statement_false|line_number_false [anything]]]
If truth_value
is non-zero, executes compound_statement_true
or jumps to line_number_true
.
If it is zero, executes compound_statement_false
or jumps to line_number_false
.
truth_value
is a numeric expression.
line_number_false
and line_number_true
are existing line numbers.
compound_statement_false
and compound_statement_true
are compound statements,
consisting of at least one statement, optionally followed by further statements separated by colons :
. The compound statements
may contain nested IF—THEN—ELSE
statements.
ELSE
clauses are optional; they
are bound to the innermost free IF
statement if nested. Additional ELSE
clauses that have no matching IF
are ignored.
THEN
and GOTO
are interchangeable; which one is chosen is independent
of whether a statement or a line number is given. GOTO PRINT 1
is fine.
GOTO
, anything after the line number is ignored.
truth_value
has a string value: Type mismatch.
truth_value
equals 0
and line_number_false
is a non-existing line number,
or
truth_value
is nonzero and line_number_true
is a non-existing line number:
Undefined line number.
INPUT
(console)
INPUT [;] [prompt {;|,}] var_0 [, var_1] ...
Prints prompt
to the screen and waits for the user to input values for the specified variables.
The semicolon before the prompt, if present,
stops a newline from being printed after the values have been entered.
If the prompt is followed by a semicolon, it is printed with a trailing ?
. If
the prompt is followed by a comma, no question mark is added.
prompt
is a string literal.
var_0, var_1, ...
are variable names or fully indexed array elements.
"
).
INPUT
.
var_n
is a numeric variable, the value entered must be
number literal.
CONT
will re-execute the
INPUT
statement.
INPUT
(files)
INPUT # file_num, var_0 [, var_1] ...
Reads string or numeric variables from a text file or the FIELD
buffer
of a random access file.
file_num
is the number of a file open in
INPUT
mode or a random-access file open in RANDOM
mode.
var_0, var_1, ...
are variable names or fully indexed array elements.
#
is mandatory. There may or may not be whitespace between INPUT
and #
.
"
).
, LF
, CR
, ,
.
LF
, CR
, ,
.
EOF
character or its 255th character.
file_num
is open to KYBD:
, INPUT#
reads from the keyboard until a
return or comma is encountered (as in a file). Arrow keys and delete are
passed as their control characters (not scancodes!) preceded by CHR$(&hFF)
.
EOF
character has been encountered: Input past end.
file_num
has a string value: Type mismatch.
file_num
is greater than 32767
: Overflow.
file_num
is less than zero: Illegal function call.
file_num
is not an open file: Bad file number.
file_num
is not open for INPUT
or RANDOM
: Bad file mode.
file_num
is open to a COM
port and this is the
first INPUT
, LINE INPUT
or INPUT$
call on that port
since the buffer has filled up completely (i.e. LOF(file_num)
has become zero):
Communication buffer overflow.
IOCTL
IOCTL [#] file_num, control_string
Raises Illegal function call.
IOCTL
sends a control string to a device.
file_num
has a string value: Type mismatch.
file_num
is not in [-32768—32767]
: Overflow.
file_num
is not an open file: Bad file number.
KEY
(macro list)
KEY {ON|OFF|LIST}
Turns the list of function-key macros on the bottom of the screen ON
or OFF
.
If LIST
is specified, prints a list of
the 10 (or 12 with syntax=tandy
) function keys
with the function-key macros defined for those keys to the console.
Most characters are represented by their symbol equivalent in the current codepage. However, some characters get a different representation, which is a symbolic representation of their effect as control characters on the screen.
Code point | Replacement | Usual glyph |
---|---|---|
&h07
|
&h0E
|
♫ |
&h08
|
&hFE
|
■ |
&h09
|
&h1A
|
→ |
&h0A
|
&h1B
|
← |
&h0B
|
&h7F
|
⌂ |
&h0C
|
&h16
|
▬ |
&h0D
|
&h1B
|
← |
&h1C
|
&h10
|
► |
&h1D
|
&h11
|
◄ |
&h1E
|
&h18
|
↑ |
&h1F
|
&h19
|
↓ |
KEY
(macro definition)
KEY key_id, string_value
Defines the string macro for function key key_id
.
Only the first 15 characters of string_value
are stored.
key_id
is a numeric expression in the range
[1—10]
(or [1—12]
when syntax=tandy
).
string_value
is a string expression.
key_id
is not in the prescribed range,
the statement is interpreted as an
event-trapping KEY
statement.
string_value
is the empty string or
the first character of string_value
is
CHR$(0)
, the function key macro is switched off and
subsequent catching of the associated function key with
INKEY$
is enabled.
key_id
is not in [-32768—32767]
: Overflow.
key_id
is not in [1—255]
: Illegal function call.
key_id
has a string value: Type mismatch.
KEY
(event switch)
KEY (key_id) {ON|OFF|STOP}
Controls event trapping of the key with identifier key_id
.
Event trapping is switched ON
or OFF
. STOP
suspends event trapping until
a KEY() ON
is executed. Up to one event can be triggered during
suspension, provided that event handling was switched on prior to suspension.
The event triggered during suspension is handled immediately after the next KEY() ON
statement.
key_id
is a numeric expression in [1—20]
.
Keys are:
1 | F1 |
2 | F2 |
3 | F3 |
4 | F4 |
5 | F5 |
6 | F6 |
7 | F7 |
8 | F8 |
9 | F9 |
10 | F10 |
11 | ↑ |
12 | ← |
13 | → |
14 | ↓ |
Keys 15 to 20 are defined using the event trapping
KEY
definition statement.
syntax=tandy
, key 11
is F11 and key 12 is F12.
Pre-defined keys 11—14 shift to 13—16.
key_id
is not in [-32768—32767]
: Overflow.
key_id
is not in [0—20]
: Illegal function call.
key_id
has a string value: Type mismatch.
KEY
(event definition)
KEY key_id, two_char_string
Defines the key to trap for key_id
.
key_id
is a numeric
expression in [15—20]
(or [17—20]
when syntax=tandy
).
two_char_string
is a string expression of length 2. The first character is interpreted as a modifier
while the second character is interpreted as a scancode.
The modifier character is a bitwise OR
combination of the following flags:
CHR$(&h80) |
Extended |
CHR$(&h40) |
Caps Lock |
CHR$(&h20) |
Num Lock |
CHR$(&h08) |
Alt |
CHR$(&h04) |
Ctrl |
CHR$(&h02) |
Shift (either side) |
CHR$(&h01) |
Shift (either side) |
CHR$(0)
.
key_id
is not in the prescribed range, no error is raised; such values are ignored.
In GW-BASIC strange things can
happen in this case: screen anomalies and crashes suggestive of unintended
memory access.
key_id
is in [1—10]
(or [1—12]
when syntax=tandy
),
the statement is interpreted as a
function-key macro definition.
key_id
is not in [-32768—32767]
: Overflow.
key_id
is not in [1—255]
: Illegal function call.
key_id
has a string value: Type mismatch.
two_char_string
is longer than two: Illegal function call.
two_char_string
has a numeric value: Type mismatch.
KILL
KILL file_spec
Deletes a file on a disk device.
file_spec
is a
valid file specification indicating the file to delete.
It must point to an existing file on a disk device.
file_spec
has a number value: Type mismatch.
file_spec
is open: File already open
file_spec
does not exist: File not found
LCOPY
LCOPY [num]
Does nothing.
num
is a numeric expression in [0—255]
.
num
is not in [-32768—32767]
: Overflow.
num
is not in [0—255]
: Illegal function call.
num
has a string value: Type mismatch.
LET
[LET] name = expression
Assigns the value of expression
to the variable or array element name
.
name
is a variable that may or may not already exist.
expression
matches that of name
: that is, all numeric types can
be assigned to each other but strings can only be assigned to strings.
name
and expression
are not of matching types: Type mismatch.
LINE
LINE [[STEP] (x0, y0)] - [STEP]
(x1, y1) [, [attr] [, [B [F]] [, pattern]]]
Draws a line or a box in graphics mode. If B
is not specified, a line is drawn
from (x0, y0)
to (x1, y1)
, endpoints inclusive.
If B
is specified, a
rectangle is drawn with sides parallel to the screen and two opposing corners
specified by (x0, y0)
and (x1, y1)
. If the starting point is not given,
the current graphics position is used as a staring point. If STEP
is
specified, (x0, y0)
is an offset from the current position and (x1, y1)
is an
offset from (x0, y0)
.
LINE
moves the current graphics position to the last given endpoint.
If F
is specified with B
, the rectangle is filled with the specified attribute.
F
and B
may be separated by zero or more spaces.
attr
is a numeric expression in [0—255]
, which
specifies the colour attribute of the line. If it is not given, the current
attribute is used.
pattern
is a numeric expression in [-32768—32767]
.
This is interpreted as a 16-bit binary pattern mask
applied to consecutive pixels in the line: a 1 bit indicates a pixel
plotted; a 0 bit indicates a pixel left untouched. The pattern starts at
the most significant bit, which is applied to the topmost endpoint. If a
box is drawn, the pattern is applied in the following counter-intuitive
sequence: (x1, y1)—(x0, y1)
,
(x1, y0)—(x0, y0)
,
then (x1, y0)—(x1, y1)
,
(x0, y0)—(x0, y1)
if y0<y1
and y0
,
y1
reversed if y1<y0
. When drawing a
filled box, LINE
ignores the pattern.
[-32768—32767]
: Overflow.
LINE INPUT
(console)
LINE INPUT [;] [prompt_literal {;|,}] string_name
Displays the prompt given in prompt_literal
and reads user input from the
keyboard, storing it into the variable string_name
. All input is read until
Enter is pressed; the first 255 characters are stored. If the ;
is given
right after LINE INPUT
, the Enter ending user input is not echoed to the
screen.
prompt_literal
is a string literal. It makes no difference whether it is
followed by a comma or a semicolon.
string_name
is a string variable or array element.
CONT
will re-execute the LINE
INPUT
statement.
INPUT
, LINE INPUT
does not end the prompt with ?
.
LINE INPUT
(files)
LINE INPUT # file_num, string_name
Reads string or numeric variables from a text file or the FIELD
buffer
of a random access file. All input is read until Enter is pressed; the first
255 characters are stored. file_num
must be the number of a file open in
INPUT
mode or a random-access file open in RANDOM
mode.
string_name
is a string variable or array element.
#
is mandatory. There may or may not be whitespace between INPUT
and #
.
CR
.
file_num
is open to KYBD:
, LINE INPUT#
reads from the keyboard until a
return or comma is encountered (as in a file). Arrow keys and delete are
passed as their control characters (not scancodes!) preceded by CHR$(&hFF)
.
EOF
char has been encountered: Input past end.
file_num
is not an open file: Bad file number.
file_num
is less than zero: Illegal function call.
file_num
is not in [-32768—32767]
: Overflow.
file_num
is not open for INPUT
or RANDOM
: Bad file mode.
file_num
has a string value: Type mismatch.
file_num
is open to a COM
port and this is the
first INPUT
, LINE INPUT
or INPUT$
call on that port
since the buffer has filled up completely (i.e. LOF(file_num)
has become zero):
Communication buffer overflow.
LIST
LIST [line_number_0|.] [-[line_number_1|.]] [, file_spec [anything]]
Prints the program to the screen or a file,
starting with line_number_0
up to and
including line_number_1
.
Also stops program execution and returns control to the user.
If the LIST
statement ends with a file specification, anything further is ignored.
In all cases, any further
statements in a compound after LIST
will be ignored, both in a program and in direct mode.
When listing to the screen, the same control characters are recognised as in the
PRINT
statement.
LIST
will not show line numbers
65531
—65535
inclusive.
By default, PC-BASIC's LIST
does show these lines. However,
showing them can be disabled with the option
strict-hidden-lines
.
line_number_0
and line_number_1
are
line numbers in the range [0—65529]
or a .
to indicate the last line edited. The line numbers do not need to exist;
they specify a range. If the range is empty, nothing is printed.
file_spec
is a
valid file specification indicating the file to list to.
If this file already exists, it will be overwritten.
65529
: Syntax error.
file_spec
has a numeric value: Type mismatch.
file_spec
ends in a colon but is not a device name or drive letter:
Bad file number.
file_spec
contains disallowed characters:
Bad file number (on CAS1:
);
Bad file name (on disk devices).
LLIST
LLIST [line_number_0|.] [-[line_number_1|.]]
Prints the program to the screen, starting with line_number_0
up to and
including line_number_1
.
Also stops program execution and returns control to the user. Any further
statements on a line after LLIST
will be ignored, both in a program and in direct mode.
LLIST
will not show line numbers
65531
—65535
inclusive.
By default, PC-BASIC's LLIST
does show these lines. However,
showing them can be disabled with the option
strict-hidden-lines
.
line_number_0
and line_number_1
are line numbers in the range [0—65529]
.
or a .
to indicate the last line edited. The line numbers do not need to exist;
they specify a range. If the range is empty, nothing is printed.
65529
: Syntax error.
LOAD
LOAD file_spec [, R]
Loads the program stored in a file into memory.
Existing variables will be cleared and any program in memory will be erased. LOAD
implies a
CLEAR
.
If ,R
is specified, keeps all data files open and runs the specified file.
file_spec
is a valid file specification indicating
the file to read the program from.
file_spec
has a numeric value: Type mismatch.
file_spec
contains disallowed characters:
Bad file number (on CAS1:
);
Bad file name (on disk devices).
file_spec
cannot be found: File not found.
LF
rather than CR LF
line endings may cause this error.
LOCATE
LOCATE [row] [, [col] [, [cursor_visible] [, [start_line] [, [stop_line] [,]]]]]
Positions the cursor at row
, col
on the screen and changes the cursor shape and visibility.
cursor_visible
may be 0 or 1. If cursor_visible
is 0, it makes
the cursor invisible; if it is 1, makes the cursor visible. This works only while a program is running.
The cursor shape is adjusted
within a character cell to start from start_line
and end on end_line
where
start_line
and end_line
are in [0—31]
. If start_line
or end_line
is
greater than the character cell height (15), substitute 15.
[-32768—32767]
: Overflow.
row
is outside the current view area: Illegal function call.
col
is greater than the current width: Illegal function call.
cursor_visible
is not in [0, 1]
([0—255]
on Tandy/PCjr): Illegal function call.
LOCK
LOCK [#] file_number [, record_0]
LOCK [#] file_number, [record_0] TO record_1
Locks a file or part of a file against access by other users. On a RANDOM
file,
record_0
is the first record locked and record_1
is the last
record locked. On any other kind of file record_0
and record_1
have no
effect. If record_0
is not specified, it is assumed to be 1. If no records
are specified, the whole file is locked.
file_number
is a numeric expression in [0—255]
.
record_0
and record_1
are numeric expressions in [1—2^25-2]
.
LOCK
command requires SHARE.EXE
to be loaded.
The maximum number of locks is specified in the MS-DOS SHARE
command. If SHARE
has
not been activated or all locks are used, LOCK
raises Permission denied.
PC-BASIC behaves as if SHARE
has been activated with unlimited locks.
file_number
is open for RANDOM
,
LOCK
and UNLOCK
statements must match in terms of record_0
and
record_1
. An non-matching UNLOCK
will raise
Permission denied.
file_num
is not in [-32768—32767]
: Overflow.
file_num
is not in [0—255]
: Illegal function call.
file_num
is not an open file: Bad file number.
LOCK
(part of) a file already locked: Permission denied.
record_0
or record_1
is not in [1—2^25-2]
: Bad record number.
LPRINT
See PRINT
.
LSET
LSET string_name = expression
Copies a string value into an existing string variable or array element. The value will be left-justified and any remaining characters are replaced by spaces.
string_name
is a string variable or array element.
expression
is a string expression.
expression
has a value that is longer than the length of the target variable,
it is truncated at the tail to the length of the target variable.
string_name
has not been allocated before, this statement has no effect.
LSET
, RSET
or
MID$
to copy values into a FIELD
buffer.
LET
is used on a FIELD
variable
instead of L|RSET
, the variable is
detached from the field and a new, normal string variable is allocated.
string_name
is not a string variable: Type mismatch.
expression
does not have a string value: Type mismatch.
MERGE
MERGE file_spec
Overlays the lines of a program from a plain-text program file into the existing program. The loaded lines overwrite existing lines if they have the same line number.
file_spec
is a valid file specification indicating
the file to read the program from.
file_spec
cannot be found: File not found.
file_spec
contains disallowed characters:
Bad file number (on CAS1:
);
Bad file name (on disk devices).
file_spec
was not saved as plain text: Bad file mode.
LF
rather than CR LF
line endings may cause this error.
MID$
(statement)
MID$(string_name, position [, length]) = substring
Replaces part of string_name
with substring
.
string_name
is a valid string variable name.
position
is a numeric expression between 1 and the string length, inclusive.
length
is a numeric expression in [0—255]
.
MID$
and (
.
substring
is longer than length
, only the first length
characters
are used.
substring
is shorter than length
, only LEN(substring)
characters
are replaced.
position
is greater than the length of string_name
:
Illegal function call, except if length
is specified as 0.
position
is not in [1—255]
: Illegal function call.
length
is not in [0—255]
: Illegal function call.
position
or length
are not in [-32768—32767]
: Overflow.
MKDIR
MKDIR dir_spec
Creates a new directory on a disk device.
dir_spec
is a valid
file specification that specifies the
path of the new directory on a disk device.
dir_spec
is not a string: Type mismatch.
MOTOR
MOTOR [num]
Does nothing.
num
is a numeric expression in [0—255]
.
num
is nonzero or omitted, and turns it off if num
is zero. This is not implemented in PC-BASIC.
num
has a string value: Type mismatch.
num
is not in [-32768—32767]
: Overflow.
num
is not in [0—255]
: Illegal function call.
NAME
NAME old_name AS new_name
Renames the disk file old_name
into new_name
.
old_name
and new_name
are valid file specifications giving the path on a disk device to the old and new filenames,
respectively.
new_name
will be modified into all-uppercase 8.3 format.
old_name
or new_name
have number values: Type mismatch.
old_name
does not exist: File not found.
old_name
is open: File already open.
new_name
exists: File already exists.
NEW
NEW
Stops execution of a program, deletes the program in memory, executes
CLEAR
and RESTORE
and returns control to the user.
NEXT
NEXT [var_0 [, var_1] ...]
Iterates a FOR—NEXT
loop: increments the loop variable and
jumps to the FOR
statement. If no variables are specified, next matches the most recent FOR
statement. Several nested NEXT
statements can be consolidated into one by
using the variable list. If one or more variables are specified, their order
must match the order of earlier FOR
statements.
var_0, var_1, ...
are numeric variables which are loop counters in a FOR
statement.
FOR
statement is found to match the NEXT
statement and variables:
NEXT without FOR.
var_0, var_1, ...
are string variables: NEXT without FOR.
[-32768, 32767]
when incremented after the final iteration: Overflow .
NOISE
NOISE source, volume, duration
Generates various kinds of noise.
source
is a numeric expression in [0—7]
.
It indicates the type of noise:
source | type | top of frequency band (Hz) |
---|---|---|
0 | periodic | 6991 |
1 | periodic | 3495 |
2 | periodic | 1747 |
3 | periodic | last tone played on voice 2 |
0 | white noise | 6991 |
1 | white noise | 3495 |
2 | white noise | 1747 |
3 | white noise | last tone played on voice 2 |
volume
is a numeric expression in [0—15]
.
duration
is a numeric expression.
Volume and duration are determined in the same way as for the
SOUND
statement; see there.
syntax={pcjr|tandy}
is set.
SOUND ON
has not been executed: Illegal function call.
duration
is not in [-65535—65535]
: Illegal function call.
volume
is not in [0—15]
: Illegal function call.
source
is not in [0—7]
: Illegal function call.
ON
(calculated jump)
ON n {GOTO|GOSUB} line_number_0 [, line_number_1] ...
Jumps to the n
th line number specified in the list. If n
is 0 or greater
than the number of line numbers in the list, no jump is performed. If GOTO
is specified,
the jump is unconditional; if GOSUB
is specified, jumps to a subroutine.
n
is a numeric expression in [0—255]
.
The expression must not start with the STRIG
, PEN
, PLAY
or TIMER
function keywords; if you need these functions, the expression must be bracketed.
line_number_0, line_number_1, ...
are existing line numbers in the program.
n
has a string value: Type mismatch.
n
is not in [-32768—32767]
, Overflow .
n
is not in [0—255]
: Illegal function call.
ON
(event trapping)
ON {COM(n)|KEY(n)|STRIG(n)|PEN|PLAY(n)|TIMER(x)}
GOSUB line_number
Defines an event trapping subroutine. The type of event is given by one of the following keywords:
COM(n) |
The event is triggered
if data is present in the input buffer of the
COMn: . n
is the port number in [1,2] .
|
KEY(n) |
The event is triggered if key n is pressed.
n is the key number [1—20]
defined in the KEY statement.
|
STRIG(n) |
They event is triggered if fire button n is pressed.
n in [0,2,4,6] refer to the
two fire triggers on two joysticks.
|
PEN |
The event is triggered if the light pen is on the screen. (In PC-BASIC, the light pen is emulated by default by the right mouse button). |
PLAY(n) |
The event is triggered if there are exactly n notes left on the
music background queue. n is a numeric expression in [1—32] .
|
TIMER(x) |
The event is triggered every x seconds after the TIMER ON
statement. x is a numeric expression in [1—86400] .
|
COM(n) ON
,
KEY(n) ON
,
STRIG(n) ON
,
PEN ON
,
PLAY ON
,
TIMER ON
n
or x
has a string value: Type mismatch.
n
is not in [-32768—32767]
: Overflow.
n
or x
is outside the specified range: Illegal function call.
ON ERROR
ON ERROR GOTO {line_number|0}
Turns error trapping on or off. When line_number
is set, any error causes the error handling
routine starting at that line number to be called; no message is printed and program execution is not stopped. The
error handling routine is ended by a RESUME
statement.
While in an error handling routine, events are paused and error trapping is
disabled. After the RESUME
statement, any triggered events are picked up in the following
order: KEY
, TIMER
, PLAY
- the order of the others is unknown.
Unlike event trapping, error trapping remains active when no program is running.
ON ERROR GOTO 0
turns off error trapping.
line_number
is an existing line number in the program.
0
.
line_number
does not exist: Undefined line number.
OPEN
OPEN mode_char, [#] file_num, file_spec [, rec_len]
OPEN file_spec [FOR {INPUT|OUTPUT|APPEND|RANDOM}]
[ACCESS {READ|WRITE|READ WRITE}]
[SHARED|LOCK {READ|WRITE|READ WRITE}]
AS [#] file_num [LEN = rec_len]
Opens a data file on a device.
file_spec
is a valid file specification.
file_num
is a numeric expression in [1—max_files]
,
where max_files
is the maximum file number (default 3).
rec_len
is a numeric expression in [1—128]
: the record length.
mode_char
is a string expression of which the first character is
one of ["I", "O", "A", "R"]
.
The FOR
modes or mode_char
are as follows:
mode_char |
FOR |
Effect |
---|---|---|
"I" |
INPUT |
Opens a text file for reading and positions the file pointer at the start. |
"O" |
OUTPUT |
Truncates a text file at the start and opens it for writing. Any data previously present in the file will be deleted. |
"A" |
APPEND |
Opens a text file for writing at the end of any existing data. |
"R" |
RANDOM |
Opens a file for random access; the file is divided in records of
length rec_len . If LEN is not specified, the record length defaults to
128. The file contents can be accessed using GET
and PUT of the FIELD
buffer; the FIELD buffer can be accessed through FIELD variables or through
PRINT# and INPUT# statements.
|
If no FOR
mode or mode_char
is specified, the file is opened for RANDOM
.
If both FOR
and ACCESS
are specified, any ACCESS
mode is allowed for
RANDOM
but for the other modes the access must match as follows:
FOR |
default ACCESS |
allowed ACCESS |
---|---|---|
INPUT |
READ |
READ |
OUTPUT |
WRITE |
WRITE |
APPEND |
READ WRITE |
READ WRITE |
RANDOM |
READ WRITE |
all |
If neither SHARED
nor LOCK
are specified. Inside this process, a file may be opened multiple
times for INPUT
or RANDOM
but only once for OUTPUT
or APPEND
, as long as it
is again opened in default mode. It may not be opened in SHARED
or any LOCK
modes.
If SHARED
, LOCK READ
, LOCK WRITE
or LOCK READ WRITE
is specified, whether
two OPEN
statements may access the same file depends on one's LOCK
status
and the other's ACCESS
status and vice versa.
For two OPEN
statements as follows:
OPEN "file" lock_1 AS 1
the following combinations are allowed:
OPEN "file" ACCESS acc_2 AS 2
Access allowed | acc_2 |
|||
---|---|---|---|---|
READ |
WRITE |
READ WRITE |
||
lock_1 |
SHARED |
yes | yes | yes |
LOCK READ |
no | yes | no | |
LOCK WRITE |
yes | no | no | |
LOCK READ WRITE |
no | no | no |
In GW-BASIC under MS-DOS with SHARE.EXE
active, these locks should be enforced
across a network as well as inside a single BASIC process. Without
SHARED
and LOCK
, the file is locked exclusively
for use by the GW-BASIC process. By contrast, in PC-BASIC,
the locks are only implemented internally. Whether other processes may access
the file will depend on the host OS.
A file specification file_spec
is a non-empty string expression of the form
"[device:]parameters"
,
where device
is a PC-BASIC device
and the form of the parameters
is specific to
the type of device. If device
is omitted,
the current device (one of the disk devices or CAS1:
)
is used.
A:
—Z:
and @:
parameters
must specify a valid file path of
the form [\][dirname\] ... filename
.
PC-BASIC follows DOS file system conventions.
Directory names are separated with
backslashes \
(even if the host OS separates paths with
forward slashes). File and directory names consist of a
8-character name and 3-character extension. Names are case insensitive.
Permissible characters for both filename and extension are the
printable ASCII characters in the range
&h20
–&h7E
excluding the characters
" * + . , / : ; < = > ? \ [ ] |
.
Spaces are allowed but leading and trailing spaces are ignored.
The names AUX
, CON
, PRN
and
NUL
are reserved as device aliases and are not legal names
for files or directories on a disk device.
A path starting with a backslash is interpreted as an absolute path,
starting at the root of the specified disk device. Otherwise, the
path is interpreted as relative to the current directory on the
specified device. The special directory name
..
refers to the parent directory of a preceding path, or the
parent directory of the current directory if no path is given.
The special directory name .
refers to the same directory as
given by the preceding path, or the current directory if no preceding path is given.
The LOAD
,
SAVE
,
BLOAD
,
BSAVE
,
CHAIN
,
MERGE
,
RUN
, and
LIST
statements
(but not OPEN
) implicitly add a default
extension .BAS
if no extension is specified. To refer
to a file name without an extension, the file specification should
end in a dot .
.
Unlike PC-BASIC, some versions of MS-DOS
allow certain characters in the range
&h7F
–&hFF
. However, their
permissibility and interpretation depends on the console code page,
which may be different from the display code page that affects GW-BASIC.
Depending on its console code page, MS-DOS will replace accented
letters by their unaccented uppercase variant.
Some DOS implementations will remove spaces from filenames;
notably, this is the case on DOSBox.
Since disk devices are mapped onto directories on the host system, DOS style names need to be mapped onto file names following the host system's (usually much less restrictive) standards. To allow access to files whose name on the host system does not conform to DOS standards, the following matching procedures are observed.
OPEN
,
KILL
,
NAME
,
CHDIR
,
MKDIR
,
RMDIR
LOAD
,
SAVE
,
BLOAD
,
BSAVE
,
CHAIN
,
MERGE
,
RUN
,
LIST
.BAS
will be implicitly added. To load a program
with no extension, end the filename in a dot. On file systems without
short filenames, it is not possible to load a program if its filename is
longer than 8.3, contains non-permissible characters or ends in a dot.
If no matching file is found for an output file name, a new file will be created with an all-caps 8.3 file name.
CAS1:
parameters
can be a file name of up to eight characters.
Cassette file names are case sensitive, have no path or extension,
may be empty and do not need to be unique. They may contain any
character in the range &h20
–&hFF
.
On the cassette device, when called in direct mode,
OPEN
,
CHAIN
,
MERGE
,
LOAD
and BLOAD
will print a message to the console
for each file found while winding the tape. The message consists
of the filename followed by a dot and the
file type and concluded with a status message. The file type is one of
the following:
BSAVE
memory imagedevice
was specified explicitly,
parameters
may also be empty. In this case the
first file of the appropriate type is opened.
SCRN:
, KYBD:
, and LPTn:
COMn:
When opening a COM
port, the file_spec
has the form
"COMn:[speed[,parity[,data[,stop[,RS][,CS[n]][,DS[n]][,CD[n]][,LF][,PE]]]]]"
The first four parameters after the device colon must be given
in the order specified but the named parameters
can be given in any order.
The meaning of the parameters is:
Parameter | Default | Meaning | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
speed |
300 |
Baud (bps) rate for the connection. speed is one of
[75, 110, 150, 300, 600, 1200, 1800, 2400, 4800, 9600] .
|
||||||||||||||||||
parity |
E |
Parity bit convention. parity is one of [S, M, O, E, N] .
|
||||||||||||||||||
data |
7 |
Data bits per byte. data must be one of [4, 5, 6, 7, 8] .
A byte consists of the data bits plus parity bit, if
any. Byte size must be in the range [5—8] :
if data is 4 ,
parity must not be N ;
if data is 8 ,
parity must be N .
|
||||||||||||||||||
stop |
1 |
The number of stop bits. stop must be 1 or 2 .
Default is 2 if speed is 75 or 110 ; 1 otherwise.
|
||||||||||||||||||
RS |
no | Suppress Request To Send. | ||||||||||||||||||
CS[n] |
CS1000 |
Set Clear To Send timeout to n milliseconds.
If n is 0 or not given, disable CTS check.
Default is CS0 if RS is set; CS1000 otherwise.
|
||||||||||||||||||
DS[n] |
DS1000 |
Set Data Set Ready timeout to n milliseconds.
If n is 0 or not given, disable DSR check.
|
||||||||||||||||||
CD[n] |
CD0 |
Set Carrier Detect timeout to n milliseconds.
If n is 0 or not given, disable CD check.
|
||||||||||||||||||
LF |
no | Send a line feed after each carriage return. | ||||||||||||||||||
PE |
no | Enable parity checking (This setting is ignored by PC-BASIC). |
COM
port is opened for RANDOM
, access is
byte-for-byte rather than through FIELD
records; PRINT#
and INPUT#
access
the port directly. rec_len
sets the number of bytes read by the GET
and
PUT
statements.
INPUT
, OUTPUT
and APPEND
modes, LEN
may be specified but is ignored.
FOR
mode specified,
the PRINT
or
INPUT
statement will raise Bad file mode.
RANDOM
I/O is attempted contravening the ACCESS
mode specified, the
PUT
or GET
statement will raise Path/File access error.
#
is optional and has no effect.
file_spec
is empty or a non-existent device: Bad file number.
FOR APPEND ACCESS WRITE
is specified: Path/File access error.
FOR
and ACCESS
mismatch in other ways: Syntax error.
COM:
file_spec
parameters do not follow the specification:
Bad file name.
CAS1:
file_spec
contains disallowed characters:
Bad file number.
OUTPUT
or APPEND
: File already open.
This is only raised for COMn:
, CASn:
and disk devices.
rec_len
or file_num
have string values: Type mismatch.
file_spec
or mode_char
have number values: Type mismatch.
file_num
is not in [-32768—32767]
: Overflow.
file_num
is not in [0—255]
: Illegal function call.
file_num
is not in [1—max_files]
: Bad file number.
rec_len
is not in [-32768—32767]
: Overflow.
rec_len
is not in [1—128]
: Illegal function call.
mode_char
is empty or the first character is not in
["I", "O", "A", "R"]
: Bad file mode.
OPTION BASE
OPTION BASE n
Sets the starting index of all arrays to n
.
n
is a literal digit 0
or 1
. Expressions are not allowed.
OPTION BASE
has not been called,
the first array allocation defaults to starting index 0.
n
is not a digit 0
or 1
: Syntax error.
OPTION BASE 1
is called but an array has already been allocated before: Duplicate definition.
OPTION BASE
is called more than once with different starting index:
Duplicate definition.
OUT
OUT port, value
Sends a byte to an emulated machine port.
The following machine ports are emulated in PC-BASIC:
port |
Effect |
---|---|
&h201 |
resets the game port (joystick port) |
&h3C5 |
sets the write bitmask for SCREEN 7 , 8 , 9 colour planes.
bitmask = 2 ^ value . |
&h3CF |
sets the read colour plane to value . |
&h3D8 |
if value = &h1A , enable composite colorburst.if value = &h1E , disable composite colorburst.Requires video={cga, tandy, pcjr} .
|
OUT &h3C4, 2
OUT &h3C5, 2 ^ plane
The sequence needed to set the colour plane is:
OUT &h3CE, 4
OUT &h3CF, plane
The initial OUT
statements currently have no effect in PC-BASIC.
port
is a numeric expression in [-32768—65535]
.
value
is a numeric expression in [0—255]
.
port
or value
has a string value: Type mismatch.
port
is not in [-32768—65535]
: Overflow.
value
is not in [-32768—32767]
: Overflow.
value
is not in [0—255]
: Illegal function call.
PAINT
PAINT [STEP] (x, y) [, attrib [, border [, background]]]
Flood-fills the screen with a colour or pattern, starting from the given seed point.
x
, y
are numeric expressions in the range [-32768—32767]
If STEP is specified, x
y
are offsets
from the current position. If the seed point is outside the visible screen
area, no flood fill is performed.
attrib
is an expression that specifies the fill attribute or pattern. If not
specified, the current foreground attribute is used.
attrib
has a number value, it must be in [0—255]
; it specifies the colour
attribute used to fill.
attrib
has a string value, it specifies a tile pattern (see below).
border
is a numeric expression in [0—255]
. It specifies the attribute
of the fill boundary (see below).
background
is a string expression that represents a background tile
pattern to ignore when determining boundaries (see below).
A tile pattern can be specified by a string of up to 255 characters. The interpretation of the string depends on the number of bits per pixel and on the current screen mode.
SCREEN 2
)
76543210
|
Byte value |
---|---|
*.......
|
&h80
|
.*......
|
&h40
|
..*.....
|
&h20
|
...*....
|
&h10
|
....*...
|
&h08
|
.....*..
|
&h04
|
......*.
|
&h02
|
PAINT (0, 0), CHR$(128)+CHR$(64)+CHR$(32)+CHR$(16)+CHR$(8)+CHR$(4)+CHR$(2)
SCREEN 7
, 8
, 9
&h03
, we now need a tile
string that is twice as long:
Attribute bit |
76543210
|
Byte value |
---|---|---|
0 |
*.......
|
&h80
|
1 |
*.......
|
&h80
|
0 |
.*......
|
&h40
|
1 |
.*......
|
&h40
|
0 |
..*.....
|
&h20
|
1 |
..*.....
|
&h20
|
0 |
...*....
|
&h10
|
1 |
...*....
|
&h10
|
0 |
....*...
|
&h08
|
1 |
....*...
|
&h08
|
0 |
.....*..
|
&h04
|
1 |
.....*..
|
&h04
|
0 |
......*.
|
&h02
|
1 |
......*.
|
&h02
|
SCREEN 1
, 3
, 4
, 5
, 6
3210
|
76543210
|
Byte value |
---|---|---|
2000 |
*.......
|
&h80
|
1000 |
.*......
|
&h40
|
0200 |
..*.....
|
&h20
|
0100 |
...*....
|
&h10
|
0020 |
....*...
|
&h08
|
0010 |
.....*..
|
&h04
|
0002 |
......*.
|
&h02
|
The tile pattern is anchored to the screen; imagine a grid starting at
(0,0)
and covering the screen. Whenever an area is tile-filled,
the tiles are put into this grid. In this way, adjacent areas will have
continuous tiling even if they were filled from different seed points.
A solid flood fill stops at pixels that have the same attribute as the fill or that have the specified border attribute, if specified. A tiling flood fill stops at the specified border attribute; if no border attribute is specified, it stops at the current foreground attribute. A tiling flood fill also stops at scan line intervals that are the same as the tiling pattern for that line, unless a background pattern is specified and the interval also equals the background pattern for that line.
SCREEN 7
, 8
, 9
, if background
equals attrib
up to the length of
attrib
: Illegal function call.
background
has a number value: Illegal function call.
border
,x
, or y
have a string value: Type mismatch.
border
,x
, or y
are not in [-32768—32767]
: Overflow.
border
is not in [0—255]
: Illegal function call.
attrib
is numeric and not in [-32768—32767]
: Overflow.
attrib
is numeric and not in [0—255]
: Illegal function call.
PALETTE
PALETTE [attrib, colour]
Assigns a colour to an attribute. All pixels with that attribute will change
colour immediately.
If no parameters are specified, PALETTE
resets to the initial setting.
attrib
is a numeric expression between 0 and the current palette
size, less one.
colour
is a numeric expression between -1 and the maximum number of
colours for the current screen mode, less one. If colour
equals -1,
the palette remains unchanged.
attrib
or colour
has a string value: Type mismatch.
attrib
or colour
is not in [-32768—32767]
: Overflow
attrib
or colour
is not in range: Illegal function call
PALETTE USING
PALETTE USING int_array_name {(|[} start_index {)|]}
Assigns new colours to all attributes.
int_array_name
is an array of integers (%
) that will supply the
new values for the palette.
start_index
is a numeric expression that
indicates at which index in the array to start mapping to the palette.
If an array entry has value -1
, the matching attribute is left unchanged.
int_array_name
has not been allocated: Illegal function call.
The array will not be automatically allocated.
int_array_name
is not an integer array: Type mismatch.
int_array_name
is too short: Illegal function call.
start_index
has a string value: Type mismatch.
start_index
is not in [-32768—32767]
: Overflow
start_index
is outside array dimensions: Subscript out of range
PCOPY
PCOPY src, dst
Copies the screen page src
to dst
. All text and graphics on dst
is
replaced by those of src
.
src
and dst
are numeric expressions between 0 and the current video
mode's number of pages, less one.
src
or dst
has a string value: Type mismatch.
src
or dst
is not in [-32768—32767]
: Overflow.
src
or dst
is out of range: Illegal function call.
PEN
(statement)PEN {ON|OFF|STOP}
Controls event trapping and read access of the light pen (emulated through the mouse in PC-BASIC).
PEN ON
switches pen reading and trapping on. PEN OFF
switches it off.
PEN STOP
suspends PEN
event trapping until PEN ON
is
executed. Up to one event can be triggered during suspension, provided that
event handling was switched on prior to suspension. The event triggered during
suspension is handled immediately after the next PEN ON
statement.
PLAY
(event switch)
PLAY {ON|OFF|STOP}
ON
: enables ON PLAY
event
trapping of the music queue.
OFF
: disables trapping.
STOP
: halts trapping until PLAY ON
is used.
Events that occur while trapping is halted will trigger immediately when
trapping is re-enabled.
PLAY
(music statement)
PLAY [mml_string_0] [, [mml_string_1] [, mml_string_2]]
Plays the tune defined by the Music Macro Language strings mml_string_0, ...
.
Unless syntax={tandy | pcjr}
is set, only the single-voice syntax is available.
The three separate MML strings correspond to the three voices of the PCjr/Tandy sound adapter.
The notes in these strings are played synchronously.
mml_string_0
, mml_string_1
, mml_string_2
are string expressions in MML.
Command | Effect |
---|---|
{A|B|C|D|E|F|G}[#|+|-][m] |
Play a note. + or # indicates sharp. - indicates flat. m is a numeric literal and
indicates duration of an m th note.
m is in the range [0—64] .
If m=0 or omitted, use the default length.
|
Nn |
Play note n , in the range [0—84] (7 octaves).n = 0 means rest. |
On |
Set the current octave to n , in the range [0—6] . Default is 4. |
> |
Increase the current octave by 1, with a maximum of 6. |
< |
Decrease the current octave by 1, with a minimum of 0. |
Pn |
Pause for the duration of an n th note.
n is in the range [0—64] .
If n=0 , this has no effect.
|
Command | Effect |
---|---|
. |
Increase the duration of the preceding note by 1/2 times its normal duration. Periods can be repeated to increase duration further. |
Ln |
Set the duration of following note to an n th note.
(n=4 is a quarter note, etc.)
n is in the range [1—64] .
|
MN |
Normal: 7/8 of the duration is sound, with 1/8 silence. Default mode. |
ML |
Legato: full duration is sound. |
MS |
Staccato: 3/4 of the duration is sound, with 1/4 silence. |
Tn |
Sets the tempo to n L4 s per minute.
n is in the range [32—255] . Default is 120.
|
These commands affect SOUND
,
PLAY
and BEEP
Command | Effect |
---|---|
MB |
Turns on background mode; sound commands exit without waiting for the
music to finish. The music keeps playing while other commands are
executed. There can be up to 16 notes in the background music queue;
if more notes are played, PLAY will block until there are only 16 left.
|
MF |
Turns off background mode; sound commands block. Default mode. |
Command | Effect |
---|---|
Xs |
Execute substring. s is one of the following:
|
Volume control is available on syntax={tandy | pcjr}
only:
Command | Effect |
---|---|
Vn
|
Set the volume to n , in the range [0—15] .
On syntax=pcjr , if SOUND ON
has not been executed, this has no effect. On syntax=tandy it does have.
|
Numeric variables n
in the commands above can be:
PLAY "L4G"
var
preceded by =
and followed by ;
.
For example, PLAY "L=VAR;G"
or PLAY "L=A(1);G"
VARPTR$(var)
preceded by =
. For example, PLAY "L=" + VARPTR$(VAR) + "G"
Note that only number literals may follow named notes and dereferencing variables or arrays is not allowed there.
It is an error to write PLAY "G=VAR;"
or PLAY "G=" + VARPTR$(VAR)
.
Use PLAY "G4"
or PLAY "L=VAR;G"
or PLAY "L=" + VARPTR$(VAR) + "G"
instead.
mml_string
has a numeric value: Type mismatch.
mml_string
has errors in the MML: Illegal function call.
SOUND ON
has not been executed, using the three-voice syntax
will raise Syntax error. This is not the case on Tandy.
POKE
POKE address, value
Sets the value of the memory byte at
segment * 16 + address
to value
,
where segment
is the current segment set with
DEF SEG
.
address
is a numeric expression in [-32768—65535]
. Negative values are
interpreted as their two's complement.
value
is a numeric expression in [0—255]
.
address
or value
has a string value: Type mismatch.
address
is not in [-32768—65535]
: Overflow.
value
is not in [-32768—32767]
: Overflow.
value
is not in [0—255]
: Illegal function call.
PSET
and PRESET
{ PSET | PRESET } [STEP] (x, y) [, attrib]
Change the attribute of a pixel on the screen at position (x, y)
.
If STEP
is specified, (x, y)
is an offset from the current position.
If attrib
is between 0 and the screen mode's palette size, the pixel is changed to
attribute attrib
. If attrib
is larger than the palette size, the pixel's
attribute is changed to the highest legal attribute value.
If attrib
is not specified, PSET
changes the attribute to the current
foreground attribute while PRESET
changes it to zero.
x
, y
are numeric expressions in [-32768—32767]
.
attrib
is a numeric expression in [0—255]
.
x
or y
has a string value: Type mismatch.
attrib
, x
or y
or the physical coordinates they translate into are not in
[-32768—32767]
: Overflow.
attrib
is not in [0—255]
: Illegal function call.
PRINT
and LPRINT
{LPRINT|{PRINT|?} [# file_num,]} [expr_0|;|,|SPC(n)|TAB(n)] ...
[USING format; uexpr_0 [{;|,} uexpr_1] ... [;|,]]
Writes expressions to the screen, printer, or file. If LPRINT
is used,
output goes to LPT1:
. If file_num
is specified, output goes to the file
open under that number. ?
is a shorthand for PRINT
.
When writing a string expression to the screen, the following control characters have special meaning. Other characters are shown as their corresponding glyph in the current codepage.
Code point | Control character | Effect |
---|---|---|
&h07
|
BEL
|
Beep the speaker. |
&h08
|
BS
|
Erase the character in the previous column and move the cursor back. |
&h09
|
HT
|
Jump to the next 8-cell tab stop. |
&h0A
|
LF
|
Go to the leftmost column in the next row; connect the rows to one logical line. |
&h0B
|
VT
|
Move the cursor to the top left of the screen. |
&h0C
|
FF
|
Clear the screen. |
&h0D
|
CR
|
Go to the leftmost column in the next row. |
&h1C
|
FS
|
Move the cursor one column to the right. |
&h1D
|
GS
|
Move the cursor one column to the left. |
&h1E
|
RS
|
Move the cursor one row up. |
&h1F
|
US
|
Move the cursor one row down. |
Expressions can optionally be separated by one or more of the following keywords:
Keyword | Effect |
---|---|
; |
Attaches two expressions tight together; strings will be printed without any space in between, numbers will have one space separating them, in addition to the space or minus sign that indicate the sign of the number. |
, |
The expression after will be positioned at the next available zone. The output file is divided in 14-character zones; if the width of the file is not a multiple of 14, the remaining spaces are unused and the first zone of the next line is used instead. If the file has a width of less than 14 characters, the zones are determined as if the file were wrapping continuously. |
SPC(n) |
Produces n spaces, where n is a numeric
expression. if n is less than zero, it defaults to zero. If n is
greater than the file width, it is taken modulo the file width.
|
TAB(n) |
Moves to column n , where n is a numeric
expression. if n is less than zero, it defaults to zero. If n is
greater than the file width, it is taken modulo the file width. If the
current column is greater than n , TAB moves to column n on the next
line.
|
If the print statement does not end in one of these four separation tokens, a newline is printed after the last expression. String expressions can be separated by one or more spaces, which has the same effect as separating by semicolons.
A USING
declaration occurs at the end of an [L]PRINT[#]
statement and writes a
formatted string to the screen, printer or file. The following tables list the format tokens
that can be used inside the format
string.
_ |
Escape character; causes the next character in the format string to be printed as is rather than interpreted as a format token. |
For string expressions:
! |
Prints the first character of a string. |
\\ |
Prints 2 or more characters of a string. A greater number of characters is
selected by separating the \ s by spaces.
|
& |
Prints the whole string. |
For numeric expressions, the format string specifies a width and alignment.
# |
Indicate a position for a digit. |
. |
Indicate the decimal point. |
, |
Before the decimal point: cause digits to be grouped in threes separated by commas. After the decimal point it is not a token. Provides one digit position. |
The number of characters in the field must not exceed 24.
Tokens preceding the number field:
+ |
Cause the sign to be printed for positive as well as negative numbers. The sign is to be printed to the left of the number. |
** |
Cause any leading spaces to be replaced with * s.
Provides two digit positions.
|
$$ |
Cause a $ to be printed to the left of the number.
Provides one digit position.
|
Tokens trailing the number field:
+ |
Cause the sign to be printed for positive as well as negative numbers. The sign will be printed to the right of the number. |
- |
Cause the sign for negative numbers to be printed
to the right of the number. Note that - preceding the field is not a token
but printed literally.
|
^^^^ |
Specify that scientific notation E+00 is to be used. |
Numeric expressions are always fully printed, even if they do not fit in the
positions specified. If the number does not fit in the allowed space, a %
is
printed preceding it.
USING
declaration ends in a comma or semicolon, no newline is printed at
the end.
USING
declaration, other elements of the PRINT
syntax such as SPC(
and TAB(
can not
be used.
expr_0, expr_1, ...
are expressions of any type.
format
is a string expression that specifies the output format.
uexpr_0, uexpr_1, ...
are expressions matching a token in the format string.
n
has a string value: Type mismatch.
n
is not in [-32768—65535]
: Overflow.
#
characters: Illegal function call.
PUT
(files)
PUT [#] file_number [, record_number]
Writes a record to the random-access file file_number
at position
record_number
.
file_number
is a numeric expression that yields the number
of an open random-access file. The #
is optional and has no effect.
record_number
is a numeric expression in [1—33554432]
(2^25
) and is interpreted as the record number.
2^25
.
record_number
is not in [1—33554432]
: Bad record number.
file_number
is not in [0—255]
: Illegal function call.
file_number
is not the number of an open file:
Bad file number.
file_number
is open under a mode other than RANDOM
:
Bad file mode.
file_number
is not specified: Missing operand.
PUT
(communications)
PUT [#] com_file_number [, number_bytes]
Writes number_bytes
bytes to the communications buffer opened under file
number com_file_number
. number_bytes
is a numeric expression between 1
and the COM
buffer length, inclusive.
bytes
is less than 1: Bad record number.
bytes
is less than 32768
and greater than the COM
buffer length: Illegal function call.
com_file_number
is not specified: Missing operand.
com_file_number
is not in [0—255]
: Illegal function call.
com_file_number
is not the number of an open file:
Bad file number.
LOF(com_file_number) = 0
and
LOC(com_file_number)=255
: Communication buffer overflow.
PUT
(graphics)
PUT (x0, y0), array_name [, {PSET|PRESET|AND|OR|XOR}]
Displays an array to a rectangular area of the graphics screen.
Usually, PUT
is used with arrays that have been stored using GET
. See GET
for the
format of the array.
The keywords have the following effect:
PSET |
Overwrite the screen location with the new image |
PRESET |
Overwrite the screen location with the inverse image |
AND |
Combines the old and new attributes with bitwise AND |
OR |
Combines the old and new attributes with bitwise OR |
XOR |
Combines the old and new attributes with bitwise XOR |
array_name
is a numeric array.
x0
, y0
are numeric expressions.
array_name
refers to a string array: Type mismatch.
x0
, y0
are string expressions: Type mismatch.
x0
, y0
are not in [-32768—32767]
: Overflow.
x0
, y0
is outside the current VIEW
or WINDOW
:
Illegal function call
RANDOMIZE
RANDOMIZE [expr]
Seeds the random number generator with expr
.
If no seed is specified, RANDOMIZE
will prompt the user
to enter a random seed. The user-provided value is rounded to an integer.
The random seed is formed of the last two bytes of that integer or expr
.
If expr
is a float (4 or 8 bytes), these are
XOR
ed with the preceding 2. The
first 4 bytes of a double are ignored.
The same random seed will lead to the same sequence of pseudorandom numbers
being generated by the RND
function.
expr
is a numeric expression.
RND
for details.
expr
has a string value: Illegal function call.
[-32768—32767]
at the prompt: Overflow.
READ
READ var_0 [, var_1] ...
Assigns data from a DATA
statement to variables. Reading starts at the current
DATA
position, which is the DATA
entry immediately after the last one read by
previous READ
statements. The DATA
position is reset
to the start by the RUN
and RESTORE
statements.
var_0
, var_1
are variables or array elements.
DATA
statements: Out of DATA.
DATA
line.
REM
{REM|'} [anything]
Ignores everything until the end of the line. The REM
statement is intended for
comments. Everything after REM
will be stored in the program unaltered and
uninterpreted. '
(apostrophe) is an alias for :REM'
; it can be placed at any
point in the program line and will ensure that the rest of the line is ignored.
Note that a colon :
does not terminate the REM
statement; the colon and everything
after it will be treated as part of the comment.
RENUM
RENUM [new|.] [, [old|.] [, increment]]
Replaces the line numbers in the program by a systematic enumeration starting
from new
and increasing by increment
. If old
is specified, line numbers
less than old
remain unchanged.
new
, old
are line numbers; the dot .
signifies the last line edited.
increment
is a line number but must not be a dot or zero.
RENUM
: AUTO
, EDIT
,
ELSE
, ERL
,
DELETE
, GOSUB
,
GOTO
, LIST
,
LLIST
, RENUM
,
RESTORE
, RESUME
,
RETURN
, RUN
,
THEN
.
CHAIN
. However, a line number
in a RUN
statement that
opens a new file will be renumbered, and incorrectly so. Furthermore, any RENUM
or AUTO
statements in a program will have all their arguments 'renumbered',
including any line number offsets or increments. However silly, this agrees with GW-BASIC's behaviour.
ERROR GOTO
will not be renumbered.
Undefined line ref in old_line
where old_line
is the line number prior to renumbering. The referenced line number will be
left unchanged, but the line's old line number will be renumbered.
[0—65529]
: Syntax error.
65529
:
Illegal function call. The line numbers up to the error have not been
changed.
increment
is empty or zero: Illegal function call.
old
is specified and new
is less than or equal to an existing line
number less than old: Illegal function call.
RESET
RESET
Closes all open files.
RESET
closes all files on disk devices.
However, in reality GW-BASIC 3.23 also closes files on tape
and any other device, making this statement identical to
CLOSE
with no arguments.
PC-BASIC follows this behaviour.
RESTORE
RESTORE [line]
Resets the DATA
pointer.
line
is a line number. If line
is not specified, the DATA
pointer is reset to the first
DATA
entry in the program. If it is specified, the DATA
pointer is
reset to the first DATA
entry in or after line
.
line
is not an existing line number: Undefined line number.
RESUME
RESUME [0|NEXT|line]
Continues normal execution after an error handling routine.
If 0
or no option is specified, re-executes the statement that caused the
error. If NEXT
is specified, executes the statement following the one that
caused the error. If line
is specified, it must be a valid line number.
RESUME
is encountered outside of an error trapping routine:
RESUME without error.
RESUME
or END
statement: No RESUME.
line
is not an existing line number: Undefined line number.
RETURN
RETURN [line]
Returns from a GOSUB
subroutine.
If line
is not specified, RETURN
jumps back
to the statement after the GOSUB
that jumped into the subroutine.
If line
is specified, it must be a valid line number. RETURN
jumps to that
line (and pops the GOSUB
stack).
When returning from an error trapping routine, RETURN
re-enables the event
trapping which was stopped on entering the trap routine.
line
is not an existing line number: Undefined line number.
RMDIR
RMDIR dir_spec
Removes an empty directory on a disk device.
dir_spec
is a
valid file specification that specifies the path and name of the directory.
dir_spec
has a numeric value: Type mismatch.
dir_spec
is an empty string: Bad file name .
RSET
RSET string_name = expression
Copies a string value into an existing string variable or array element. The value will be right-justified and any remaining characters are replaced by spaces.
string_name
is a string variable or array element.
expression
is a string expression.
expression
has a value that is longer than the length of the target variable,
it is truncated at the tail to the length of the target variable.
string_name
has not been allocated before, this statement has no effect.
LSET
, RSET
or
MID$
to copy values into a FIELD
buffer.
LET
is used on a FIELD
variable
instead of L|RSET
, the variable is
detached from the field and a new, normal string variable is allocated.
string_name
is not a string variable: Type mismatch.
expression
does not have a string value: Type mismatch.
RUN
RUN [line_number [anything]|file_spec [, R]]
Executes a program.
Existing variables will be
cleared and any program in memory will be erased. RUN
implies a CLEAR
If ,R
is specified after file_spec
, files are kept open; if not, all files are closed.
line_number
is a valid line number in the current program.
If specified, execution starts from this line number. The rest of the RUN
statement is ignored in this case.
file_spec
, if specified,
is a valid file specification indicating
the file to read the program from.
line_number
is not a line number in the current program: Undefined line number.
file_spec
cannot be found: File not found.
file_spec
is an empty string: Bad file number.
SAVE
SAVE file_spec [, {A|P}]
Stores the current program in a file.
,A
is specified, the program will be saved in plain text format.
,P
is specified, the program will be saved in protected format.
When a protected program is loaded in GW-BASIC, it cannot be LIST
ed or SAVE
d in non-protected
format.
file_spec
is a valid file specification
indicating the file to store to.
file_spec
has a number value: Type mismatch.
file_spec
is an empty string: Bad file number.
file_spec
contains disallowed characters:
Bad file number (on CAS1:
);
Bad file name (on disk devices).
strict-protect
is enabled, the current program is protected and ,P
is not specified:
Illegal function call.
SCREEN
(statement)
SCREEN [mode] [, [colorburst] [, [apage] [, [vpage] [, erase]]]]
Change the video mode, composite colorburst, active page and visible page. Video modes are described in the Video Modes section.
mode
is a numeric expression that sets the screen mode.
colorburst
is a numeric expression. See notes below.
apage
is a numeric expression that sets the active page.
vpage
is a numeric expression that sets the visible page.
erase
is a numeric expression in the range [0, 1, 2]
.
It is only legal with syntax={pcjr, tandy}
. See notes below.
The video modes are as follows:
SCREEN 0
Text modeega
SCREEN 1
CGA colourega
2 pages pcjr
tandy
SCREEN 2
CGA monochromeega
2 pages pcjr
tandy
SCREEN 3
Low-res 16-colour pcjr
tandy
SCREEN 3
Hercules monochrome hercules
SCREEN 3—255
Altissima risoluzione olivetti
SCREEN 4
Med-res 4-colour pcjr
tandy
SCREEN 5
Med-res 16-colour pcjr
tandy
Note: a minimum of 32768 bytes of video memory must be
reserved to use this video mode. Use the statement
CLEAR ,,,32768!
or the option
video-memory=32768
.
SCREEN 6
High-res 4-colour pcjr
tandy
Note: a minimum of 32768 bytes of video memory must be
reserved to use this video mode. Use the statement
CLEAR ,,,32768!
or the option
video-memory=32768
.
SCREEN 7
EGA colour ega
SCREEN 8
EGA colour ega
SCREEN 9
EGA colour ega
SCREEN 10
EGA monochrome ega
monitor=mono
On CGA, Tandy and PCjr, colorburst
has the following effects, depending on the
type of monitor - RGB (default) or composite:
mode |
colorburst |
CGA mode | Effect (composite) | Effect (RGB) |
---|---|---|---|---|
0 | 0 | 0, 2 | greyscale | default palette |
0 | 1 | 1, 3 | colour | default palette |
1 | 0 | 4 | colour | default palette |
1 | 1 | 5 | greyscale | alternate palette |
On SCREEN 2
, colorburst
has no effect; on a composite monitor, colour artifacts
can be enabled on this screen through OUT
(see there). On SCREEN 3
and up, colorburst
has no effect.
By default, if the mode
changes or the colorburst
changes between zero and non-zero, the old page and the new page of the screen
are cleared. On syntax={pcjr, tandy}
,
the erase
parameter can be used to change this behaviour.
Its values are as follows:
erase |
Effect |
---|---|
0 |
Do not erase any screen page |
1 (default) |
If the mode changes or the colorburst
changes between zero and non-zero, the old page and the new page of the screen
are cleared. |
2 |
If the mode changes or the colorburst
changes between zero and non-zero, all pages of the screen are cleared. |
SCREEN 1
.
[-32768—32767]
: Overflow.
mode
is not an available video mode number for your video card setting: Illegal function call.
vpage
, apage
are not between 0 and the number of pages for the
chosen video mode, less one: Illegal function call.
colorburst
is not in [0—255]
: Illegal function call.
erase
is not in [0, 1, 2]
:
Illegal function call.
SHELL
SHELL [command]
Starts a subshell on the console.
The type of shell is determined by your OS. On Unix systems, an sh
shell is
started. On Windows systems, a CMD.EXE
shell is started.
If command
is specified, the command is executed on the shell and execution
returns to the program.
command
is a string expression.
shell=native
option is not specified, this statement does nothing.
command
has a number value: Type mismatch.
SOUND
(tone)
SOUND frequency, duration [, volume [, voice]]
Produces a sound at frequency
Hz for duration/18.2
seconds.
On PCjr and Tandy, the volume and voice channel can additionally be specified.
If PLAY "MB"
has been executed, SOUND
plays in the background. If PLAY "MF"
has been executed, sound plays in the foreground and the interpreter blocks
until the sound is finished. Foreground mode is default. Unlike PLAY
, the
sound played by the most recent SOUND
statement always plays in the background,
even if PLAY "MF"
has been entered. In background mode, each SOUND
statement
counts as 1 toward the length of the queue reported by the PLAY
function.
frequency
is a numeric expression in [37—32767]
or 0
(for syntax={advanced | pcjr}
)
or in [-32768—32767]
(for syntax=tandy
).
duration
is a numeric expression in [0—65535]
.
volume
is a numeric expression in [0, 15]. 0 is silent, 15 is full
volume; every step less reduces the volume by 2 dB. (For syntax={pcjr | tandy}
)
voice
is a numeric expression in [0, 2], indicating which of the
three tone voice channels is used for this sound. (For syntax={pcjr | tandy}
)
duration
is zero, any active background sound is stopped and
the sound queue is emptied.
duration
is zero, volume
and voice
must not be specified.
duration
is less than .022
but nonzero, the sound will be played in
background and continue indefinitely until another sound statement is
executed. This is also the behaviour for negative duration
.
frequency
equals 32767
or 0
, a silence of length duration
is queued.
frequency
is not in its allowed range, and duration
is not zero:
Illegal function call.
duration
is zero and more than two arguments are specified:
Syntax error.
syntax={ pcjr | tandy }
is not set and more than two arguments are specified:
Syntax error.
frequency
is not in [-32768—32767]
:
Overflow.
duration
is not in [-65535—65535]
:
Illegal function call.
volume
is not in [0—15]
:
Illegal function call.
voice
is not in [0—2]
:
Illegal function call.
SOUND
(switch)
SOUND {ON|OFF}
Toggles the availability of advanced sound capabilities on PCjr and Tandy. This includes 3-voice sound, noise generation and volume control.
syntax={pcjr | tandy}
.
SOUND ON
would turn on the external speaker as
well as make advanced sound capabilities available. On PC-BASIC, both the
internal and the external speaker are emulated through the same sound
system.
syntax={ pcjr | tandy }
is not set:
Syntax error.
STOP
STOP
Breaks program execution, prints a Break
message on the console and returns control to the user. Files are not closed.
It is possible to resume program execution at the next statement using
CONT
.
STRIG
(switch)
STRIG {ON|OFF}
Has no effect.
STRIG
(event switch)
STRIG[ ](button) {ON|OFF|STOP}
Switches event trapping of the joystick trigger button
ON
or OFF
.
STRIG (button) STOP
suspends event trapping until
STRIG (button) ON
is executed. Up to one event can be triggered during
suspension, provided that event handling was switched on prior to suspension.
The event triggered during suspension is handled immediately after the next STRIG (button) ON
statement.
button |
return value |
---|---|
0 | 1st joystick 1st trigger |
2 | 2nd joystick 1st trigger |
4 | 1st joystick 2nd trigger |
6 | 2nd joystick 2nd trigger |
button
is a numeric expression in [0, 2, 4, 6]
.
button
has a string value: Type mismatch.
button
is not in [-32768—32767]
: Overflow.
button
is not in [0, 2, 4, 6]
: Illegal function call.
SWAP
SWAP var_0, var_1
Exchanges variables var_0
and var_1
.
var_0
is a FIELD
variable and var_1
is not, then
SWAP
will reverse those roles.
var_0
and var_1
are previously defined variables of
the same type.
var_0
or var_1
is undefined: Illegal function call.
var_0
and var_1
are not the same: Type mismatch.
SYSTEM
SYSTEM
Exits the interpreter.
SYSTEM
quits the PC-BASIC interpreter immediately without further interaction.
Any unsaved program or data will be lost.
TERM
TERM
Load and run the program defined by the pcjr-term
option.
By default, as on the IBM PCjr, this is a
built-in serial terminal emulator application.
This statement is only available with
syntax={pcjr|tandy}
.
TIME$
(statement)
TIME$ = time
Sets the current BASIC time to time
.
"HH:mm:ss"
where
00<=HH<24
, 00<=mm<60
and 00<=ss<60
.
TIME$
and
DATE$
functions in the same interpreter session.
The system time is not changed, unlike GW-BASIC under MS-DOS.
time
has a numeric value: Type mismatch.
time
is not of the correct form: Illegal function call.
TIMER
(statement)
TIMER {ON|OFF|STOP}
ON
: enables ON TIMER
event
trapping of the timer clock.
OFF
: disables trapping.
STOP
: halts trapping until TIMER ON
is used.
Events that occur while trapping is halted will trigger immediately when
trapping is re-enabled.
TRON
and TROFF
{TRON|TROFF}
Turns line number tracing on or off. If line number tracing is on, BASIC prints
a tag [100] to the console when program line 100
is executed, and so forth.
UNLOCK
UNLOCK [#] file_number [, record_0]
UNLOCK [#] file_number, [record_0] TO record_1
Unlocks a file or part of it that has previously been locked with LOCK
.
file_number
is a numeric expression in [0—255]
.
record_0
and record_1
are numeric expressions in [1—2^25-2]
.
file_number
is not in [-32768—32767]
: Overflow.
file_number
is not in [0—255]
: Illegal function call.
file_number
is not an open file: Bad file number.
file_number
is open for RANDOM
,
LOCK
and UNLOCK
statements must match in terms of record_0
and
record_1
. An non-matching UNLOCK
will raise
Permission denied.
record_0
or record_1
is not in [1—2^25-2]
: Bad record number.
VIEW
VIEW [[SCREEN] (x0, y0)-(x1, y1) [, [fill] [, border]]]
Defines a graphics viewport. Graphics drawn outside the viewport will
not be shown. (x0, y0)
, (x1, y1)
are absolute screen coordinates of two
opposing corners of the area.
Unless SCREEN
is specified, after a VIEW
statement the coordinate
system is shifted such that (0, 0)
becomes the top left coordinate of the viewport.
If VIEW
is called without arguments, the viewport is reset to the whole
screen.
fill
is an attribute. The viewport will be
filled with this attribute.
border
is an attribute. A border will be drawn
just outside the viewport with this attribute.
[-32768—32767]
: Overflow.
VIEW PRINT
VIEW PRINT top_row TO bottom_row
Defines the text scrolling area of the screen. LOCATE
statements,
cursor movement and scrolling will be limited to the scrolling area.
top_row
and bottom_row
are
numeric expressions in [1—24]
.
syntax={pcjr | tandy}
and
KEY OFF
is set, bottom_row
may be 25.
Otherwise, screen row 25 cannot be part of the
scrolling area.
top_row
or bottom_row
is not in [1—24]
: Illegal function call.
WAIT
WAIT port, and_mask [, xor_mask]
Waits for the value of (INP(port)
XOR xor_mask) AND
and_mask
to become nonzero.
Event handling is suspended until WAIT
returns.
If xor_mask
is not specified, it defaults to 0
.
INP
.
port
is not in [-32768—65535]
: Overflow.
and_mask
or xor_mask
are not in [0—255]
: Type mismatch.
WEND
WEND
Iterates a WHILE—WEND
loop: jumps to the matching
WHILE
statement, where its
condition can be checked.
WHILE—WEND
loops can be nested. WEND
jumps to the most recent WHILE
statement that has not been closed by another WEND
.
WHILE
statements have been closed by another
WEND
or no WHILE
statement has been executed before:
WEND without WHILE.
WHILE
WHILE expr
Initiates a WHILE—WEND
loop.
If expr
evaluates to zero, WHILE
jumps
to the statement immediately after the matching
WEND
. If not, execution continues.
expr
is a numeric expression.
WEND
is found: WHILE without WEND.
expr
has a string value: Type mismatch.
WIDTH
(console)
WIDTH num_columns [, [num_rows] [,]]
Sets the screen width to 20, 40 or 80 columns.
SCREEN 1
(40) ↔ SCREEN 2
(80)SCREEN 7
(40) ↔ SCREEN 8
(80)SCREEN 7
(40) ← SCREEN 9
(80)SCREEN 3
. Additionally, the following changes occur:SCREEN 3
(20) → SCREEN 1
(40)SCREEN 3
(20) → SCREEN 2
(80)SCREEN 4
(40) → SCREEN 2
(80)SCREEN 5
(40) ↔ SCREEN 6
(80)num_columns
is either a literal 20
,
40
or 80
or a numeric expression in parentheses.
The trailing comma is optional and has no effect.
num_rows
is optional and must equal 25. If
syntax={pcjr | tandy}
is set,
num_rows
may be in [0—25]
but its value is ignored.
num_columns
is a string expression: Type mismatch.
num_columns
is not in [-32768—32767]
: Overflow.
num_columns
is not in [0—255]
: Illegal function call.
num_columns
is not a literal and not bracketed: Illegal function call.
num_rows
is not in its accepted range: Illegal function call.
WIDTH
(devices and files)
WIDTH {#file_num,|device_name,|LPRINT} num_columns
Sets the line width for a file or a device.
When a write operation passes beyond the column width, a CR LF
sequence is
inserted.
If a device is specified, it does not need to have a file open to it; the width setting will be the default width next time a file is opened to that device.
If device_name
is "LPT1:"
or LPRINT
is specified, the device width setting affects LPRINT
and LLIST
.
If device_name
is "SCRN:"
, "KYBD:"
, or omitted, the screen width is changed.
In this case, num_columns
must be one of 20, 40 or 80.
See the notes at WIDTH
(console) for side effects.
file_num
is a numeric expression which is the number of an open file.
device_name
is a string expression that is one of
"KYBD:"
, "SCRN:"
, "LPT1:"
, "LPT2:"
,
"LPT3:"
, "COM1:"
, "COM2:"
, "CAS1:"
num_columns
is a numeric expression.
device_name
is not one of the allowed devices: Bad file name.
device_name
is "SCRN:"
, "KYBD:"
and num_columns
is not 20, 40 or
80: Illegal function call.
file_num
or num_columns
are strings: Type mismatch.
file_num
or num_columns
are not in [-32768—32767]
: Overflow.
file_num
or num_columns
are not in [0—255]
: Illegal function call.
file_num
is not an open file: Bad file mode.
WINDOW
WINDOW [[SCREEN] (x0, y0)-(x1, y1)]
Define logical coordinates for the viewport.
If SCREEN
is not specified,
the bottom left of the screen is mapped to the lower coordinates;
the top right of the screen is mapped to the higher coordinates.
If SCREEN
is specified,
the top left of the screen is mapped to the lower coordinates;
the bottom right of the screen is mapped to the higher coordinates.
If WINDOW
is called without arguments, the logical coordinates are
reset to the viewport coordinates.
x0
, y0
, x1
, y1
are numeric expressions.
x0 = x1
or y0 = y1
: Illegal function call.
WRITE
WRITE [# file_num,] expr_0 [{,|;} expr_1] ...
Writes values to a file or the screen in machine-readable form. Values are
separated by commas and the line is ended with a CR LF
sequence. Strings are
delimited by double quotes "
. No padding spaces are inserted.
When writing to the screen, the same control characters are recognised as for the
PRINT
statement.
expr_0, expr_1, ...
are expressions whose value is to be printed.
file_num
has a string value: Type mismatch.
file_num
is open for INPUT
: Bad file mode.
1 |
NEXT without FOR
A |
2 |
Syntax error
The BASIC syntax is incorrect. A statement or expression
has been mistyped or called in one of many incorrect ways. This
error is also raised on a |
3 |
RETURN without GOSUB
A |
4 |
Out of DATA
A |
5 |
Illegal function call
A statement, function or operator has been called with parameters outside the accepted range. This error is also raised for a large variety of other conditions – check the reference for the statement or function called. |
6 |
Overflow
A numeric expression result or intermediate value is too large for the required number format. |
7 |
Out of memory
There is not enough free BASIC memory to complete the operation. Too much memory is consumed by the program; variables, arrays and strings, or execution stacks for loops, subroutines or user-defined functions. |
8 |
Undefined line number
A reference is made to a line number that does not exist in the program. |
9 |
Subscript out of range
An array index (subscript) is used that is outside the range
reserved for that array by the |
10 |
Duplicate Definition
A |
11 |
Division by zero
An attempt is made to divide a number by zero or by a number that is too small to distinguish from zero within the number format's precision. |
12 |
Illegal direct
A |
13 |
Type mismatch
The expression used is of a type that cannot be converted to the required type for the function or statement. Most commonly, this is raised if a string argument is supplied to a statement or function that expects a number, or vice versa. |
14 |
Out of string space
There is not enough free BASIC memory to store the string variable. |
15 |
String too long
A string expression result or intermediate value is longer than 255 characters. |
16 |
String formula too complex |
17 |
Can't continue
The |
18 |
Undefined user function
The |
19 |
No RESUME
The program terminates inside an error trapping
routine that has not been closed with |
20 |
RESUME without error
A |
21 | unused |
22 |
Missing operand
An operator expression misses an operand or a function or statement is not supplied with sufficient parameters. |
23 |
Line buffer overflow
An |
24 |
Device Timeout
The handshake has failed on a serial device or a tape device has reached the end of tape. |
25 |
Device Fault |
26 |
FOR without NEXT
A |
27 |
Out of paper
An attempt is made to write to a printer which is out of paper or to another parallel device which has raised an out-of-paper condition. |
28 |
unused |
29 |
WHILE without WEND
A |
30 |
WEND without WHILE
A |
31—49 | unused |
50 |
FIELD overflow
An attempt is made to read, write, or define a |
51 |
Internal error
The |
52 |
Bad file number
A file number is accessed to which no file is open, or the file number used in an |
53 |
File not found
A named file on a disk device cannot be found. |
54 |
Bad file mode
The requested file mode in an |
55 |
File already open
An attempt is made to open a file to a file number that is already in use;
or an attempt is made to open a file for |
56 |
unused |
57 |
Device I/O error
An I/O error has occured during input/output to a device. This includes faming errors, CRC check failures and unexpected end-of-tape on cassette devices. |
58 |
File already exists
The proposed new name of a disk file in a |
59—60 |
unused |
61 |
Disk full
There is insufficient free space on the disk device to complete the operation. |
62 |
Input past end
An attempt is made to retrieve input from a file that has passed its end of file. |
63 |
Bad record number
A random-access file record number is referenced that is outside the permitted range. |
64 |
Bad file name
The file name or other device parameter string in a file specification is malformed or contains illegal characters. |
65 |
unused |
66 |
Direct statement in file
A line with no line number is encountered in a plain-text program file. |
67 |
Too many files |
68 |
Device Unavailable
An attempt is made to access a device that does not exist or is not enabled. |
69 |
Communication buffer overflow
A serial device is receiving more data than fits in its buffer. |
70 |
Permission Denied
The requested access to a file is not granted due to
|
71 |
Disk not Ready
The disk device is not ready for access. For example, there is no diskette in a floppy drive or the drive lock is open. |
72 |
Disk media error |
73 |
Advanced Feature |
74 |
Rename across disks
An attempt is made to use the |
75 |
Path/File access error
An attempt is made to create a directory that already exists or to remove a directory that is not empty. |
76 |
Path not found
An |
77 |
Deadlock |
Any error code that does not have a message associated to it will generate the message Unprintable error.
If an error occurs in direct mode, the error message is printed as above.
If the error occurs in a program, the message is supplemented with the
line number in which the error occurred. For example,
Illegal function call in 100
indicates that the illegal function call took place in line number 100
.
If a Syntax error occurs during program execution, the error message is followed by a listing of the program line in which the error occurred, wth the cursor positioned at the location where the error was raised.
A Division by zero error or, in a floating point calculation, an Overflow, will not interrupt execution unless it occurs within an error handling routine. The error message will be printed on the console and the result of the offending calculation will be taken to be the maximum value that fits in the appropriate floating-point variable. Overflow in an integer calculation will always interrupt execution like other errors.
CONT
statement or by a user
keyboard interrupt (such as Ctrl+Break). If the
interrupt happens in a program, the Break message will be
supplemented with the line number in which the interrupt occurred.
INPUT
statement does not match the expected format. The number or type of
inputs is not correct. Re-enter all inputs.
RENUM
statement encountered
a reference to the line number ref_num
which is not defined in the program. The reference occurs on line number
line_num
.
The undefined line number reference will not be renumbered.
A tokenised program file on a disk device has the following format.
FF
Bytes | Format | Meaning |
---|---|---|
2 | Unsigned 16-bit little-endian integer. | Memory location of the line following the current one. This is used internally by GW-BASIC but ignored when a program is loaded. |
2 | Unsigned 16-bit little-endian integer. | The line number. |
Variable | Tokenised BASIC, see below. | The contents of the line. |
1 |
00 (NUL byte)
|
End of line marker. |
1A
is written to mark the end of file. This is optional;
the file will be read without problems if it is omitted.
The printable ASCII characters in the range 20
—7E
are used for string literals, comments, variable names,
and elements of statement syntax that are not reserved words.
Reserved words are represented by their reserved word tokens and
numeric literals are represented by numeric token sequences.
Numeric literals are stored in tokenised programs
according to the following representation. All numbers are positive; negative numbers are stored
simply by preceding the number with EA
, the token for -
.
Class | Bytes | Format |
---|---|---|
Indirect line numbers | 3 |
0E followed by an unsigned 16-bit little-endian integer.
|
Octal integers | 3 |
0B followed by an unsigned 16-bit little-endian integer.
|
Hexadecimal integers | 3 |
0C followed by an unsigned 16-bit little-endian integer.
|
Positive decimal integers less than 11 | 1 |
Tokens 11 —1B represent 0—10.
|
Positive decimal integers less than 256 | 2 |
0F followed by an unsigned 8-bit integer.
|
Other decimal integers | 3 |
1C followed by a two's complement signed 16-bit little-endian integer.
GW-BASIC will recognise a negative number encountered this way but it will not store
negative numbers itself using the two's complement, but rather by preceding the positive
number with EA .
|
Single precision floating-point number | 5 |
1D followed by a four-byte single in Microsoft Binary Format.
|
Double precision floating-point number | 9 |
1F followed by an eight-byte double in Microsoft Binary Format.
|
Most keywords in PC-BASIC are reserved words. Reserved words are represented in a tokenised program by a single- or double-byte token. The complete list is below.
All function names and operators are reserved words and all statements start with a reserved word
(which in the case of LET
is optional). However, the converse is not true:
not all reserved words are statements, functions, or operators.
For example, TO
and SPC(
only occur as part of a statement syntax.
Furthermore, some keywords that form part of statement syntax are not reserved words:
examples are AS
, BASE
, and ACCESS
.
Keywords that are not reserved words are spelt out in full text in the tokenised source.
A variable or user-defined function name must not be identical to a reserved word. The list below is an exhaustive list of reserved words that can be used to determine whether a name is legal.
81
END
82
FOR
83
NEXT
84
DATA
85
INPUT
86
DIM
87
READ
88
LET
89
GOTO
8A
RUN
8B
IF
8C
RESTORE
8D
GOSUB
8E
RETURN
8F
REM
90
STOP
91
PRINT
92
CLEAR
93
LIST
94
NEW
95
ON
96
WAIT
97
DEF
98
POKE
99
CONT
9C
OUT
9D
LPRINT
9E
LLIST
A0
WIDTH
A1
ELSE
A2
TRON
A3
TROFF
A4
SWAP
A5
ERASE
A6
EDIT
A7
ERROR
A8
RESUME
A9
DELETE
AA
AUTO
AB
RENUM
AC
DEFSTR
AD
DEFINT
AE
DEFSNG
AF
DEFDBL
B0
LINE
B1
WHILE
B2
WEND
B3
CALL
B7
WRITE
B8
OPTION
B9
RANDOMIZE
BA
OPEN
BB
CLOSE
BC
LOAD
BD
MERGE
BE
SAVE
BF
COLOR
C0
CLS
C1
MOTOR
C2
BSAVE
C3
BLOAD
C4
SOUND
C5
BEEP
C6
PSET
C7
PRESET
C8
SCREEN
C9
KEY
CA
LOCATE
CC
TO
CD
THEN
CE
TAB(
CF
STEP
D0
USR
D1
FN
D2
SPC(
D3
NOT
D4
ERL
D5
ERR
D6
STRING$
D7
USING
D8
INSTR
D9
'
DA
VARPTR
DB
CSRLIN
DC
POINT
DD
OFF
DE
INKEY$
E6
>
E7
=
E8
<
E9
+
EA
-
EB
*
EC
/
ED
^
EE
AND
EF
OR
F0
XOR
F1
EQV
F2
IMP
F3
MOD
F4
\
FD81
CVI
FD82
CVS
FD83
CVD
FD84
MKI$
FD85
MKS$
FD86
MKD$
FD8B
EXTERR
FE81
FILES
FE82
FIELD
FE83
SYSTEM
FE84
NAME
FE85
LSET
FE86
RSET
FE87
KILL
FE88
PUT
FE89
GET
FE8A
RESET
FE8B
COMMON
FE8C
CHAIN
FE8D
DATE$
FE8E
TIME$
FE8F
PAINT
FE90
COM
FE91
CIRCLE
FE92
DRAW
FE93
PLAY
FE94
TIMER
FE95
ERDEV
FE96
IOCTL
FE97
CHDIR
FE98
MKDIR
FE99
RMDIR
FE9A
SHELL
FE9B
ENVIRON
FE9C
VIEW
FE9D
WINDOW
FE9E
PMAP
FE9F
PALETTE
FEA0
LCOPY
FEA1
CALLS
FEA5
PCOPY
FEA7
LOCK
FEA8
UNLOCK
FF81
LEFT$
FF82
RIGHT$
FF83
MID$
FF84
SGN
FF85
INT
FF86
ABS
FF87
SQR
FF88
RND
FF89
SIN
FF8A
LOG
FF8B
EXP
FF8C
COS
FF8D
TAN
FF8E
ATN
FF8F
FRE
FF90
INP
FF91
POS
FF92
LEN
FF93
STR$
FF94
VAL
FF95
ASC
FF96
CHR$
FF97
PEEK
FF98
SPACE$
FF99
OCT$
FF9A
HEX$
FF9B
LPOS
FF9C
CINT
FF9D
CSNG
FF9E
CDBL
FF9F
FIX
FFA0
PEN
FFA1
STICK
FFA2
STRIG
FFA3
EOF
FFA4
LOC
FFA5
LOF
The following additional reserved words are activated by the option
syntax={pcjr|tandy}
.
FEA4
NOISE
FEA6
TERM
The following additional reserved word is activated by the debug
option.
It is specific to PC-BASIC and not present in GW-BASIC.
FFFF
DEBUG
The tokens 10
, 1E
and 0D
are
known to be used internally by GW-BASIC. They should not appear in a
correctly stored tokenised program file.
Floating point numbers in GW-BASIC and PC-BASIC are represented in Microsoft Binary Format (MBF), which differs from the IEEE 754 standard used by practically all modern software and hardware. Consequently, binary files generated by either BASIC are fully compatible with each other and with some applications contemporary to GW-BASIC, but not easily interchanged with other software. QBASIC, for example, uses IEEE floats.
MBF differs from IEEE in the position of the sign bit and in using only 8 bits for the exponent, both in single- and in double-precision. This makes the range of allowable numbers in an MBF double-precision number smaller, but their precision higher, than for an IEEE double: an MBF single has 23 bits of precision, while an MBF double has 55 bits of precision. Both have the same range.
Unlike IEEE, the Microsoft Binary Format does not support signed zeroes, subnormal numbers, infinities or not-a-number values.
MBF floating point numbers are represented in bytes as follows:
Here, E0 is the exponent byte and the other bytes form the mantissa, in little-endian order so that M1 is the most significant byte. The most significant bit of M1 is the sign bit, followed by the most significant bits of the mantissa: M1 = s0 f1 f2 f3 f4 f5 f6 f7. The other bytes contain the less-significant mantissa bits: M2 = f8 f9 fA fB fC fD fE fF, and so on.
The value of the floating-point number is v = 0 if E0 = 0 and v = (-1) s0 × mantissa × 2 E0 - 128 otherwise, where the mantissa is formed as a binary fraction mantissa = 0 . 1 f1 f2 f3 ...
The protected format is an encrypted form of the tokenised format. GW-BASIC would refuse to show the source code of such files. This protection scheme could easily be circumvented by changing a flag in memory. Deprotection programs have circulated widely for decades and the decryption algorithm and keys were published in a mathematical magazine.
A protected program file on a disk device has the following format.
FE
0B 0A 09 08 07 06 05 04 03 02 01
1E 1D C4 77 26 97 E0 74 59 88 7C
A9 84 8D CD 75 83 43 63 24 83 19 F7 9A
0D 0C 0B 0A 09 08 07 06 05 04 03 02 01
1A
is written to mark the end of file. This is optional;
the file will be read without problems if it is omitted. Since the
end-of-file marker of the tokenised program is included in the encrypted
content, a protected file is usually one byte longer than its
unprotected equivalent.
BSAVE
file formatA memory-dump file on a disk device has the following format.
FD
Bytes | Format | Meaning |
---|---|---|
2 | Unsigned 16-bit little-endian integer. | Segment of the memory block. |
2 | Unsigned 16-bit little-endian integer. | Offset of the first byte of the memory block. |
2 | Unsigned 16-bit little-endian integer. | Length of the memory block in bytes. |
1A
is written to mark the end of file. This is optional;
the file will be read without problems if it is omitted.
Files on cassette are stored as frequency-modulated sound. The payload format of files on cassette is the same as for files on disk device, but the headers are different and the files may be split in chunks.
A 1-bit is represented by a single 1 ms wave period (1000 Hz). A 0-bit is represented by a single 0.5 ms wave period (2000 Hz).
A byte is sent as 8 bits, most significant first. There are no start- or stopbits.
A file is made up of two or more records. Each record has the following format:
Length | Format | Meaning |
---|---|---|
256 bytes |
All FF
|
2048 ms pilot wave at 1000 Hz, used for calibration. |
1 bit |
0
|
Synchronisation bit. |
1 byte |
16 (SYN )
|
Synchronisation byte. |
256 bytes | Data block. | |
2 bytes | Unsigned 16-bit big-endian integer | CRC-16-CCITT checksum. |
4 bytes |
All FF
|
End of record marker. |
Tokenised, protected and BSAVE
files consist of a header record
followed by a single record which may contain multiple 256-byte data blocks, each followed by the 2 CRC bytes.
Plain text program files and data files consist of a header record followed by multiple single-block records.
Bytes | Format | Meaning |
---|---|---|
1 |
A5
|
Header record magic byte |
8 | 8 characters | Filename. |
1 |
File type. 00 for data file,
01 for memory dump,
20 or A0 for protected,
40 for plain text program,
80 for tokenised program.
|
|
2 | Unsigned 16-bit little-endian integer | Length of next data record, in bytes. |
2 | Unsigned 16-bit little-endian integer | Segment of memory location. |
2 | Unsigned 16-bit little-endian integer | Offset of memory location. |
1 |
00
|
End of header data |
239 |
All 01
|
Filler |
Bytes | Format | Meaning |
---|---|---|
1 | 8-bit unsigned integer | Number of payload bytes in last record, plus one. If zero, the next record is not the last record. |
255 | Payload data. If this is the last record, any unused bytes are filled by repeating the last payload byte. |
Depending on context, PC-BASIC will treat a code point in
the control characters range as a control character or as a
glyph defined by the active codepage which by
default is codepage 437. Code points of
&h80
or higher are always interpreted as a
codepage glyph.
This is a list of the American Standard Code for Information Interchange (ASCII).
ASCII only covers 128 characters and defines the code point ranges
&h00
–&h1F
and &h7F
as control characters which do not have a printable glyph assigned
to them. This includes such values as the Carriage Return (CR
)
character that ends a program line.
In the context of this documentation, character &h1A
(SUB
)
will usually be indicated as EOF
since it plays the role of end-of-file marker in DOS.
_0 |
_1 |
_2 |
_3 |
_4 |
_5 |
_6 |
_7 |
_8 |
_9 |
_A |
_B |
_C |
_D |
_E |
_F |
|
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0_ |
NUL |
SOH |
STX |
ETX |
EOT |
ENQ |
ACK |
BEL |
BS |
HT |
LF |
VT |
FF |
CR |
SO |
SI |
1_ |
DLE |
DC1 |
DC2 |
DC3 |
DC4 |
NAK |
SYN |
ETB |
CAN |
EM |
SUB |
ESC |
FS |
GS |
RS |
US |
2_ |
|
! |
" |
# |
$ |
% |
& |
' |
( |
) |
* |
+ |
, |
- |
. |
/ |
3_ |
0 |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
: |
; |
< |
= |
> |
? |
4_ |
@ |
A |
B |
C |
D |
E |
F |
G |
H |
I |
J |
K |
L |
M |
N |
O |
5_ |
P |
Q |
R |
S |
T |
U |
V |
W |
X |
Y |
Z |
[ |
\ |
] |
^ |
_ |
6_ |
` |
a |
b |
c |
d |
e |
f |
g |
h |
i |
j |
k |
l |
m |
n |
o |
7_ |
p |
q |
r |
s |
t |
u |
v |
w |
x |
y |
z |
{ |
| |
} |
~ |
DEL |
This table shows the characters that
are produced by the 256 single-byte code points when
the DOS Latin USA codepage 437 is loaded, which is the default.
Code points &h00
and &h20
–&h7E
are fixed while the other characters, as well as any double-byte characters,
can be redefined by loading another codepage.
_0 |
_1 |
_2 |
_3 |
_4 |
_5 |
_6 |
_7 |
_8 |
_9 |
_A |
_B |
_C |
_D |
_E |
_F |
|
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0_ |
|
☺ |
☻ |
♥ |
♦ |
♣ |
♠ |
• |
◘ |
○ |
◙ |
♂ |
♀ |
♪ |
♫ |
☼ |
1_ |
► |
◄ |
↕ |
‼ |
¶ |
§ |
▬ |
↨ |
↑ |
↓ |
→ |
← |
∟ |
↔ |
▲ |
▼ |
2_ |
|
! |
" |
# |
$ |
% |
& |
' |
( |
) |
* |
+ |
, |
- |
. |
/ |
3_ |
0 |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
: |
; |
< |
= |
> |
? |
4_ |
@ |
A |
B |
C |
D |
E |
F |
G |
H |
I |
J |
K |
L |
M |
N |
O |
5_ |
P |
Q |
R |
S |
T |
U |
V |
W |
X |
Y |
Z |
[ |
\ |
] |
^ |
_ |
6_ |
` |
a |
b |
c |
d |
e |
f |
g |
h |
i |
j |
k |
l |
m |
n |
o |
7_ |
p |
q |
r |
s |
t |
u |
v |
w |
x |
y |
z |
{ |
| |
} |
~ |
⌂ |
8_ |
Ç |
ü |
é |
â |
ä |
à |
å |
ç |
ê |
ë |
è |
ï |
î |
ì |
Ä |
Å |
9_ |
É |
æ |
Æ |
ô |
ö |
ò |
û |
ù |
ÿ |
Ö |
Ü |
¢ |
£ |
¥ |
₧ |
ƒ |
A_ |
á |
í |
ó |
ú |
ñ |
Ñ |
ª |
º |
¿ |
⌐ |
¬ |
½ |
¼ |
¡ |
« |
» |
B_ |
░ |
▒ |
▓ |
│ |
┤ |
╡ |
╢ |
╖ |
╕ |
╣ |
║ |
╗ |
╝ |
╜ |
╛ |
┐ |
C_ |
└ |
┴ |
┬ |
├ |
─ |
┼ |
╞ |
╟ |
╚ |
╔ |
╩ |
╦ |
╠ |
═ |
╬ |
╧ |
D_ |
╨ |
╤ |
╥ |
╙ |
╘ |
╒ |
╓ |
╫ |
╪ |
┘ |
┌ |
█ |
▄ |
▌ |
▐ |
▀ |
E_ |
α |
ß |
Γ |
π |
Σ |
σ |
µ |
τ |
Φ |
Θ |
Ω |
δ |
∞ |
φ |
ε |
∩ |
F_ |
≡ |
± |
≥ |
≤ |
⌠ |
⌡ |
÷ |
≈ |
° |
∙ |
· |
√ |
ⁿ |
² |
■ |
|
PC-BASIC uses PC/XT scancodes, which originated on the 83-key IBM Model F keyboard
supplied with the IBM PC 5150. The layout of this keyboard was quite distinct
from modern standard keyboards with 101 or more keys, but keys on a modern keyboard produce
the same scancode as the key with the same function on the Model F. For example,
the key that (on a US keyboard) produces the \ was located next to
the left Shift key on the Model F keyboard and has scancode
&h2B
. The (US) backslash key still has this scancode, even
though it is now usually found above the Enter key.
To further complicate matters, keyboards for different locales have their layout remapped in software rather than in hardware, which means that they produce the same scancode as the key that on a US keyboard is in the same location, regardless of which character they actually produce.
Therefore, the A on a French keyboard will produce the same scancode as the Q on a UK or US keyboard. The aforementioned US \ key is identified with the key that is generally found to the bottom left of Enter on non-US keyboards. For example, on my UK keyboard this is the # key. Non-US keyboards have an additional key next to the left Shift which on the UK keyboard is the \. Therefore, while this key is in the same location and has the same function as the Model F \, it has a different scancode.
In the table below, the keys are marked by their function on a US keyboard, but it should be kept in mind that the scancode is linked to the position, not the function, of the key.
Key | Scancode |
---|---|
Esc | 01 |
1 ! | 02 |
2 @ | 03 |
3 # | 04 |
4 $ | 05 |
5 % | 06 |
6 ^ | 07 |
7 & | 08 |
8 * | 09 |
9 ( | 0A |
0 ) | 0B |
- _ | 0C |
= + | 0D |
Backspace | 0E |
Tab | 0F |
q Q | 10 |
w W | 11 |
e E | 12 |
r R | 13 |
t T | 14 |
y Y | 15 |
u U | 16 |
i I | 17 |
o O | 18 |
p P | 19 |
[ { | 1A |
] } | 1B |
Enter | 1C |
Ctrl | 1D |
a A | 1E |
s S | 1F |
d D | 20 |
f F | 21 |
g G | 22 |
h H | 23 |
j J | 24 |
k K | 25 |
l L | 26 |
; : | 27 |
' " | 28 |
` ~ | 29 |
Left Shift | 2A |
\ | | 2B |
z Z | 2C |
x X | 2D |
c C | 2E |
v V | 2F |
b B | 30 |
n N | 31 |
m M | 32 |
, < | 33 |
. > | 34 |
/ ? | 35 |
Right Shift | 36 |
keypad * PrtSc | 37 |
Alt | 38 |
Space | 39 |
Caps Lock | 3A |
F1 | 3B |
F2 | 3C |
F3 | 3D |
F4 | 3E |
F5 | 3F |
F6 | 40 |
F7 | 41 |
F8 | 42 |
F9 | 43 |
F10 | 44 |
Num Lock | 45 |
Scroll Lock Pause | 46 |
keypad 7 Home | 47 |
keypad 8 ↑ | 48 |
keypad 9 Pg Up | 49 |
keypad - | 4A |
keypad 4 ← | 4B |
keypad 5 | 4C |
keypad 6 → | 4D |
keypad + | 4E |
keypad 1 End | 4F |
keypad 2 ↓ | 50 |
keypad 3 Pg Dn | 51 |
keypad 0 Ins | 52 |
keypad . Del | 53 |
SysReq | 54 |
\ | (Non-US 102-key) | 56 |
F11 | 57 |
F12 | 58 |
Left Logo (Windows 104-key) | 5B |
Right Logo (Windows 104-key) | 5C |
Menu (Windows 104-key) | 5D |
ひらがな/カタカナ Hiragana/Katakana (Japanese 106-key) | 70 |
\ _ (Japanese 106-key) | 73 |
変換 Henkan (Japanese 106-key) | 79 |
無変換 Muhenkan (Japanese 106-key) | 7B |
半角/全角 Hankaku/Zenkaku (Japanese 106-key) | 29 |
¥ | (Japanese 106-key) | 7D |
한자 Hanja (Korean 103-key) | F1 |
한/영 Han/Yeong (Korean 103-key) | F2 |
\ ? ° (Brazilian ABNT2) | 73 |
keypad . (Brazilian ABNT2) | 7E |
Alongside scancodes, most keys also carry
a character value the GW-BASIC documentation calls extended ASCII.
Since this is a rather overloaded term, we shall use the abbreviation
e-ASCII exclusively for these values.
The values returned by the
INKEY$
function are e-ASCII values.
e-ASCII codes are one or
two bytes long; single-byte codes are simply ASCII codes whereas
double-byte codes consist of a NUL
character plus
a code indicating the key pressed. Some, but certainly not all,
of these codes agree with the keys' scancodes.
Unlike scancodes, e-ASCII codes of unmodified keys and those of keys modified by Shift, Ctrl or Alt are all different.
Unmodified, Shifted and Ctrled e-ASCII codes are connected to a key's meaning, not its location. For example, the e-ASCII for Ctrl+a are the same on a French and a US keyboard. By contrast, the Alted codes are connected to the key's location, like scancodes. The US keyboard layout is used in the table below.
Key | e-ASCII | e-ASCII Shift | e-ASCII Ctrl | e-ASCII Alt |
---|---|---|---|---|
Esc | 1B |
1B |
1B |
|
1 ! | 31 |
21 |
00 78 |
|
2 @ | 32 |
40 |
00 03 |
00 79 |
3 # | 33 |
23 |
00 7A |
|
4 $ | 34 |
24 |
00 7B |
|
5 % | 35 |
25 |
00 7C |
|
6 ^ | 36 |
5E |
1E |
00 7D |
7 & | 37 |
26 |
00 7E |
|
8 * | 38 |
2A |
00 7F |
|
9 ( | 39 |
28 |
00 80 |
|
0 ) | 30 |
29 |
00 81 |
|
- _ | 2D |
5F |
1F |
00 82 |
= + | 3D |
2B |
00 83 |
|
Backspace | 08 |
08 |
7F |
00 8C |
Tab | 09 |
00 0F |
00 8D |
00 8E |
q Q | 71 |
51 |
11 |
00 10 |
w W | 77 |
57 |
17 |
00 11 |
e E | 65 |
45 |
05 |
00 12 |
r R | 72 |
52 |
12 |
00 13 |
t T | 74 |
54 |
14 |
00 14 |
y Y | 79 |
59 |
19 |
00 15 |
u U | 75 |
55 |
15 |
00 16 |
i I | 69 |
49 |
09 |
00 17 |
o O | 6F |
4F |
0F |
00 18 |
p P | 70 |
50 |
10 |
00 19 |
[ { | 5B |
7B |
1B |
|
] } | 5D |
7D |
1D |
|
Enter | 0D |
0D |
0A |
00 8F |
a A | 61 |
41 |
01 |
00 1E |
s S | 73 |
53 |
13 |
00 1F |
d D | 64 |
44 |
04 |
00 20 |
f F | 66 |
46 |
06 |
00 21 |
g G | 67 |
47 |
07 |
00 22 |
h H | 68 |
48 |
08 |
00 23 |
j J | 6A |
4A |
0A |
00 24 |
k K | 6B |
4B |
0B |
00 25 |
l L | 6C |
4C |
0C |
00 26 |
; : | 3B |
3A |
||
' " | 27 |
22 |
||
` ~ | 60 |
7E |
||
\ | | 5C |
7C |
1C |
|
z Z | 7A |
5A |
1A |
00 2C |
x X | 78 |
58 |
18 |
00 2d |
c C | 63 |
43 |
03 |
00 2E |
v V | 76 |
56 |
16 |
00 2F |
b B | 62 |
42 |
02 |
00 30 |
n N | 6E |
4E |
0E |
00 31 |
m M | 6D |
4D |
0D |
00 32 |
, < | 2C |
3C |
||
. > | 2E |
3E |
||
/ ? | 2F |
3F |
||
PrtSc | 00 72 |
00 46 |
||
Space | 20 |
20 |
20 |
00 20 |
F1 | 00 3B |
00 54 |
00 5E |
00 68 |
F2 | 00 3C |
00 55 |
00 5F |
00 69 |
F3 | 00 3D |
00 56 |
00 60 |
00 6A |
F4 | 00 3E |
00 57 |
00 61 |
00 6C |
F5 | 00 3F |
00 58 |
00 62 |
00 6D |
F6 | 00 40 |
00 59 |
00 63 |
00 6E |
F7 | 00 41 |
00 5A |
00 64 |
00 6F |
F8 | 00 42 |
00 5B |
00 65 |
00 70 |
F9 | 00 43 |
00 5C |
00 66 |
00 71 |
F10 | 00 44 |
00 5D |
00 67 |
00 72 |
F11 (Tandy) | 00 98 |
00 A2 |
00 AC |
00 B6 |
F12 (Tandy) | 00 99 |
00 A3 |
00 AD |
00 B7 |
Home | 00 47 |
00 47 |
00 77 |
|
End | 00 4F |
00 4F |
00 75 |
|
PgUp | 00 49 |
00 49 |
00 84 |
|
PgDn | 00 51 |
00 51 |
00 76 |
|
↑ | 00 48 |
00 48 |
||
← | 00 4B |
00 87 |
00 73 |
|
→ | 00 4D |
00 88 |
00 74 |
|
↓ | 00 50 |
00 50 |
||
keypad 5 | 35 |
35 |
05 |
|
Ins | 00 52 |
00 52 |
||
Del | 00 53 |
00 53 |
PC-BASIC (rather imperfectly) emulates the memory of real-mode MS-DOS.
This means that memory can be addressed in segments of 64 KiB.
Each memory address is given by the segment value and the 0--65535
byte offset with respect to that segment.
Note that segments overlap: the actual memory address is found by segment*16 + offset
.
The maximum memory size that can be addressed by this scheme is thus 1 MiB, which was the size of the conventional and upper
memory in real-mode MS-DOS.
Areas of memory with a special importance are:
Segment | Name | Purpose |
---|---|---|
&h0000
|
Low memory | Holds machine information, among other things |
&h13AD (may vary)
|
Data segment | Program code, variables, arrays, strings |
&hA000 (EGA) &hB000 (MDA) &hB800 (CGA) |
Video segment | Text and graphics on visible and virtual screens |
&hC000
|
-- | RAM font definition, among other things |
&hF000
|
Read-only memory | ROM font definition, among other things |
The data segment is organised as follows. The addresses may vary depending on the settings of various options; given here are the default values for GW-BASIC 3.21.
Offset | Size (bytes) | Function |
---|---|---|
&h0000
|
3429
|
Interpreter workarea. Unused in PC-BASIC; can be adjusted with
the --reserved-memory option.
|
&h0D65
|
(max-files+1) * 322
|
File blocks: one for the program plus one for each file allowed by --max-files |
&h126D
|
3 + c
|
Program code. An empty program uses 3 bytes. |
&h1270 + c
|
v
|
Scalar variables. |
&h1270 + c + v
|
a
|
Array variables. |
&hFDFC - s
|
a
|
String variables, filled downward from &hFDFC
|
&hFDFC
|
512
|
BASIC stack, size set by CLEAR statement.
|
&hFFFE
|
Top of data segment, set by CLEAR statement.
|
PC-BASIC would not exist without those contributing code, reporting bugs, sending in patches, and documenting GW-BASIC's behaviour. Thank you all!
PC-BASIC depends on the following open-source projects:
Building PC-BASIC would have been impossible without the immense amounts of technical documentation that has been made available online. It has proven not to be feasible to compile a complete list of the documentation used. Many thanks to all those who make technical information freely available, and apologies to those whose contribution I have failed to acknowledge here.
PC-BASIC is developed using Git source control, GEdit and Atom text editors on an Ubuntu Linux system and hosted on GitHub and SourceForge.
Packaging and documentation depends on the following projects:
These excellent emulators have been indispensable tools in documenting the behaviour of various Microsoft BASIC dialects.