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.
|
|
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 | Raise Illegal function call |