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.
Functions
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.
Parameters
ASC
val = ASC(char)
Returns the code point (ASCII value) for the first character of char
.
Parameters
-
char
is an expression with
a string value.
Errors
-
char
has a numeric value: Type mismatch.
-
char
equals ""
: Illegal function call.
ATN
y = ATN(x)
Returns the inverse tangent of x
.
Parameters
-
x
is a numeric expression that gives
the angle in radians.
Notes
-
Unless PC-BASIC is run with the
double
option, this function
returns a single-precision value.
-
ATN(x)
differs in the least significant digit from GW-BASIC.
Errors
-
x
has a string value: Type mismatch.
CDBL
y = CDBL(x)
Converts the numeric expression x
to a double-precision value.
Errors
-
x
has a string value: Type mismatch.
CHR$
char = CHR$(x)
Returns the character with code point x
.
Parameters
-
x
is a numeric expression in the range [0—255]
.
Errors
-
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.
Halves are rounded away from zero, so that e.g.
CINT(2.5) = 3
and CINT(-2.5) = -3
.
Errors
-
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.
Parameters
-
angle
is a numeric expression that
gives the angle in radians.
Notes
-
The return value usually differs from the value returned by GW-BASIC in the least significant figure.
Errors
-
angle
has a string value: Type mismatch.
CSNG
y = CSNG(x)
Converts the numeric expression x
to a single-precision value
by Gaussian rounding.
Errors
-
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]
.
Notes
-
This function takes no arguments.
CVI
y = CVI(s)
Converts a two-byte string to a signed integer.
Parameters
-
s
is a string expression that represents an integer using
little-endian two's complement encoding. Only the first two bytes are used.
Errors
-
s
has a numeric value: Type mismatch.
CVS
y = CVS(s)
Converts a four-byte string to a single-precision floating-point number.
Parameters
-
s
is a string expression that represents a single-precision
number in Microsoft Binary Format. Only the first four bytes are used.
Errors
-
s
has a numeric value: Type mismatch.
CVD
y = CVD(s)
Converts an eight-byte string to a double-precision floating-point number.
Parameters
-
s
is a string expression that represents a double-precision
number in Microsoft Binary Format. Only the first eight bytes are used.
Errors
-
s
has a numeric value: Type mismatch.
DATE$
(function)
s = DATE$
Returns the system date as a string in the format "mm-dd-yyyy"
.
Notes
-
This function takes no arguments.
ENVIRON$
value = ENVIRON[ ]$(x)
Returns an environment variable.
Parameters
x
is an expression.
-
If
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. The environment variable must be an
ASCII string and will be converted to uppercase on case-sensitive systems.
-
If
x
has a numeric value, it must be in [1—255]
. Returns the x
th entry in
the environment table.
Errors
-
x
is the empty string: Illegal function call.
-
x
contains non-ASCII characters: 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.
Notes
-
If
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.
Errors
-
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.
-
The file with number
file_num
is in OUTPUT or APPEND mode:
Bad file mode.
ERDEV
zero = ERDEV
Returns 0.
Notes
-
In GW-BASIC, returns the value of a device error.
-
This function is not implemented in PC-BASIC.
-
This function takes no arguments.
ERDEV$
empty = ERDEV[ ]$
Returns the empty string.
Notes
-
In GW-BASIC, returns the device name of a device error.
-
This function is not implemented in PC-BASIC.
-
This function takes no arguments.
ERL
error_line = ERL
Returns the line number where the last error was raised.
Notes
-
If the error was
raised by a direct statement, returns 65535.
-
If no error has been raised,
returns 0.
-
This function takes no arguments.
ERR
error_code = ERR
Returns the number of the last error.
Notes
-
If no error has been raised, returns 0.
-
If the last error was a Syntax error raised by a direct statement, returns 0.
-
This function takes no arguments.
EXP
y = EXP(x)
Returns the exponential of x
, i.e. e
to the power x
.
Parameters
-
x
is a number-
valued expression.
Notes
-
Unless PC-BASIC is run with the
double
option, this function returns a single-precision
value.
-
The return value sometimes differs in the least significant digit from GW-BASIC. For
large values of
x
, the difference may be 3 digits.
Errors
-
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.
Parameters
-
x
is a numeric expression in [0—3]
.
Notes
-
In GW-BASIC, this function returns extended error information from MS-DOS.
-
This function is not implemented in PC-BASIC.
Errors
-
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.
Parameters
-
number
is a numeric expression.
Notes
-
FIX
truncates towards zero: it removes the fractional part. By contrast, INT
truncates towards negative infinity.
Errors
-
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.
Parameters
-
name
is the name of a previously defined function.
-
arg_0, arg_1, ...
are expressions, given as parameters to the function.
Errors
-
No function named
name
is defined:
Undefined user function.
-
The number of parameters differs from the function definition:
Syntax error.
-
The type of one or more parameters differs from the function definition:
Type mismatch.
-
The return type is incompatible with the function name's sigil:
Type mismatch.
-
The function being called is recursive or mutually recursive:
Out of memory.
FRE
free_mem = FRE(x)
Returns the available BASIC memory.
Parameters
x
is an expression.
-
If
x
has a numeric value, it is ignored.
-
If
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
.
Parameters
-
x
is a
numeric expression in [-32768—65535]
. Values for
negative x
are shown as two's-complement.
Errors
-
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.
Notes
-
This function takes no arguments.
-
When a function key F1–F10 is pressed,
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.
Parameters
port
is a numeric expression in [0—65535]
.
Notes
-
Only a limited number of machine ports are emulated in PC-BASIC.
Errors
-
port
is not in [-32768—65535]
: Overflow.
-
port
has a string value: Type mismatch.
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.
Parameters
-
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.
Notes
-
This is a blocking read. It will wait for characters if there are none
in the buffer.
-
All control characters except Ctrl+Break, Ctrl+Scroll Lock and Pause
are passed to the string by
INPUT$
. Ctrl+Break and Ctrl+Scroll Lock break
execution whereas Pause halts until another key is pressed (and not read).
-
When reading from the keyboard directly or through
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.
Errors
-
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
.
Parameters
-
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.
Notes
-
If
child
is not a substring of parent
occurring at or before start
,
INSTR
returns 0.
Errors
-
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.
Parameters
Notes
-
FIX
truncates towards zero: it removes the
fractional part. By contrast, INT
truncates towards negative infinity.
-
If
number
is a string expression, INT
returns its value unchanged.
IOCTL$
result = IOCTL[ ]$ ([#] file_num)
Raises Illegal function call.
Notes
-
In GW-BASIC,
IOCTL$
reads the reply to
IOCTL
from a device.
-
This function is not implemented in PC-BASIC.
Errors
-
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.
-
Otherwise: Illegal function call
LEFT$
child = LEFT$(parent, num_chars)
Returns the leftmost num_chars
characters of parent
.
Parameters
-
parent
is a string expression.
-
num_chars
is a numeric expression in [0—255]
.
Notes
-
If
num_chars
is zero or parent
is empty, LEFT$
returns
an empty string.
-
If
num_chars
is greater than the length of parent
,
returns parent
.
Errors
-
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
.
Parameters
-
string
is a string
expression.
Errors
-
string
has a number value: Type mismatch.
LOC
location = LOC(file_num)
Returns the current location in the file opened under number file_num
.
-
If the file is opened for
INPUT
, OUTPUT
or APPEND
, LOC
returns the number
of 128-byte blocks read or written since opening the file.
-
If the file is opened for
RANDOM
, LOC
returns the record number last read or
written.
-
If the file is opened to a
COM
device, LOC
returns the number of characters
in the input buffer, with a maximum of 255.
-
If the file is opened to
KYBD:
, LOC
returns 0.
Parameters
-
file_num
is a numeric expression in the range [0—255]
.
Notes
-
file_num
must not be preceded by a #
.
-
In
OUTPUT
or APPEND
mode, before any writes LOC
returns 0. After the 128th
character is written, LOC
returns 1.
-
In
INPUT
mode, before any reads LOC
returns 1. After the 129th character
is read, LOC
returns 2.
-
If
text-encoding
is set, characters may be encoded by sequences of more than one byte.
LOC
will return the number of bytes rather than the number of encoded characters.
Errors
-
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
.
Parameters
-
file_num
is a numeric expression in the range [0—255]
.
Notes
-
If
file_num
is open to a COM:
device, LOF
returns the number of bytes
free in the input buffer.
Errors
-
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.
Notes
-
If
text-encoding
is set, characters may be encoded by sequences of more than one byte.
LOF
will return the number of bytes rather than the number of encoded characters.
LOG
y = LOG(x)
Returns the natural logarithm of x
.
Parameters
-
x
is a numeric expression greater than zero.
Notes
-
Unless PC-BASIC is run with the
double
option, this function returns a single-precision value.
-
LOG(x)
can differ from GW-BASIC by 1 in the least significant digit.
Errors
-
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.
Parameters
-
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:
.
Notes
-
When entering direct mode,
LPT1:
(but not other printers)
is flushed and its position is reset to 1.
Errors
-
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.
Parameters
-
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]
.
Errors
-
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.
Errors
-
double
has a string value: Type mismatch.
MKI$
bytes = MKI$(int)
Returns the internal 2-byte little-endian representation of an integer.
Errors
-
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.
Errors
-
single
has a string value: Type mismatch.
OCT$
octal = OCT$(x)
Returns a string with the octal representation of x
.
Parameters
-
x
is a
numeric expression in [-32768—65535]
. Values for
negative x
are shown as two's-complement.
Errors
-
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
.
Parameters
-
address
is a numeric expression in [-32768—65535]
. Negative values are interpreted as their
two's complement.
Notes
-
The memory is only partly emulated in PC-BASIC. See Memory model for supported addresses.
Outside emulated areas,
PEEK
returns 0.
-
Values for particular memory address can be preset on the command line
using the
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.
Errors
-
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
:
Parameters
-
mode
is a numeric expression in [0—9]
.
Notes
-
In PC-BASIC, for pen down read mouse button pressed. For pen
position read mouse pointer position.
Errors
-
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—32]
.
Parameters
-
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.
Notes
-
There are at most 32 notes in the music queue. However, unless the articulation is
set to legato, there are short gaps between each note; these are counted as
separate notes in the queue. Effectively, the queue length is thus 16 for the default
and staccato articulations and 32 for legato.
Errors
-
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:
Parameters
-
fn
is a numeric expression in [0—3]
.
Notes
-
Initially, in text mode,
PMAP
returns 0.
-
In GW-BASIC,
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.
Errors
-
Any of the parameters has a string value: Type mismatch.
-
A physical coordinate is not in
[-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
:
Parameters
-
fn
is a numeric expression in [0—3]
.
Notes
-
In text mode, returns the active coordinate of any previous graphics mode;
if no graphics mode has been active, returns 0.
Errors
-
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
.
Parameters
-
x
, y
are numeric expressions in [-32768—32767]
.
Notes
-
If
x
,y
is outside the screen, returns -1.
Errors
-
Function is called in text mode: Illegal function call.
-
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]
.
Parameters
-
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
.
Parameters
-
parent
is a string expression.
-
num_chars
is a numeric expression in [0—255]
.
Errors
-
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)
.
Parameters
x
is a numeric expression.
-
If
x
is zero, RND
repeats the last
pseudo-random number.
-
If
x
is greater than zero, a new pseudorandom number is
returned.
-
If
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
.
Notes
-
PC-BASIC's
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
.
- It should be
noted, however, that this is a very poor random number generator: its parameters imply a recurrence period of
224, meaning that after less than 17 million calls
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.
Errors
-
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
.
Parameters
-
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.
Errors
-
Any parameter has a string value: Type mismatch.
-
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.
Notes
-
In GW-BASIC, the
SCREEN
function has anomalous error behaviour:
constructions which for other functions would raise Syntax error or
Missing operand instead raise Illegal function call. This
behaviour is not replicated in PC-BASIC.
SGN
sign = SGN(number)
Returns the sign of number
: 1
for positive, 0
for zero and -1
for negative.
Parameters
-
number
is a numeric expression.
Errors
-
number
has a string value: Type mismatch.
SIN
sine = SIN(angle)
Returns the sine of angle
.
Parameters
-
angle
is a numeric expression giving
the angle in radians.
Notes
-
Unless PC-BASIC is run with the
double
option, this function returns a single-precision value.
-
The sine returned usually differs from the value returned by GW-BASIC in the least significant figure.
Errors
-
angle
has a string value:
Type mismatch.
SPACE$
spaces = SPACE$(number)
Returns a string of number
spaces.
Parameters
-
number
is a numeric expression in [0—255]
.
Errors
-
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
.
Parameters
-
number
is a numeric expression.
Notes
-
Unless PC-BASIC is run with the
double
option, this function returns a single-precision value.
Errors
-
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.
Parameters
-
axis
is a numeric expression in [0—3]
and indicates which axis to read.
Errors
-
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
.
Parameters
-
number
is a numeric expression.
Errors
-
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:
Parameters
-
mode
is a numeric expression in [0—7]
.
Notes
-
The
STRIG
function returns correct results regardless of the
STRIG ON
status or whether STRIG(0)
has been called first.
Errors
-
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
.
Parameters
-
If
char
is a numeric expression, it must be in [0—255]
and is
interpreted as the code point of the character.
-
If
char
is a string expression, its first character is used.
Errors
-
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
.
Parameters
-
angle
is a numeric expression giving
the angle in radians.
Notes
-
Unless PC-BASIC is run with the
double
option, this function returns a single-precision value.
-
The tangent returned usually differs from the value returned by GW-BASIC in the least significant figure.
-
For
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.
Errors
-
angle
has a string value: Type mismatch.
TIME$
(function)
time = TIME$
Returns the current BASIC time in the form "HH:mm:ss"
.
Notes
-
This function takes no arguments.
TIMER
(function)
seconds = TIMER
Returns the number of seconds since midnight on the internal BASIC
clock.
Notes
-
TIMER
updates in ticks of 1/20 second.
-
The least-significant two bytes of
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.
-
This function takes no arguments.
USR
value = USR[n](expr)
Raises Illegal function call.
Parameters
-
n
is a digit [0—9]
.
-
expr
is an expression.
Notes
-
In GW-BASIC, calls a machine-code function and returns its return value.
-
This function is not implemented in PC-BASIC.
Errors
-
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.
Notes
-
Spaces before or even inside a number are ignored:
VAL(" 1 0")
returns 10
.
-
If
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.
Errors
-
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
.
Parameters
-
name
is a
previously defined variable or fully indexed array element.
-
file_num
is a legal file number.
Notes
-
VARPTR
can be used with PEEK
to read a variable's internal representation.
-
If
name
is an undefined array element, it will be implicitly allocated in the same way as if it had been used in an expression.
Errors
-
name
is a scalar that 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.
name
is a fully indexed array element (which may or may not have been defined) or a previously-defined scalar variable.
The first byte is the length of the record the pointer points to:
- 2
- for integers
- 3
- for strings (length + pointer to string space)
- 4
- for single-precision floats
- 8
- for double-precision floats
The last two bytes are the pointer address (as returned by
VARPTR
) in little-endian order.
Notes
-
If
name
is an undefined array element, it will be implicitly allocated in the same way as if it had been used in an expression.
Errors
-
name
is a scalar that has not been previously defined: Illegal function call.
Statements
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.
Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
Parameters
-
Line numbering starts at
line_number
, if specified. If .
is specified, line
numbering starts at the last program line that was stored. Otherwise, line
numbering starts at 10
.
-
Each next line number is incremented by
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
.
Errors
-
line_number
is not an unsigned-integer value in [0—65529]
:
Syntax error.
-
When automatic line numbering is enabled and Enter is pressed on an empty line with number larger than
65519
: Undefined line number.
-
increment
is 0
:
Illegal function call.
BEEP
BEEP
Beep the speaker at 800Hz for 0.25s.
Errors
-
If a Syntax error is raised, the beep is still produced.
BEEP
(switch)
BEEP {ON|OFF}
Switches the internal speaker on or off.
Notes
-
Only legal with the
syntax={pcjr|tandy}
option.
-
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.
Parameters
-
The string expression
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.
Errors
-
The loaded file is not in
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.
Parameters
-
The string expression
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.
-
If
offset
or length
are negative, their two's
complement will be used.
Errors
-
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
and CALLS
{CALL|CALLS} address_var [( p0 [, p1] ... )]
Does nothing.
Notes
-
In GW-BASIC,
CALL
or CALLS
executes a machine language subroutine.
-
This statement is not implemented in PC-BASIC.
Parameters
-
address_var
is a numeric variable name.
-
p0, p1, ...
are variable names or array elements.
Errors
-
address_var
is a string variable: Type mismatch.
-
address_var
is a literal or expression: 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.
-
If
ALL
is specified, all variables are transferred. If not, the variables
specified in a COMMON
statement are transferred.
-
If
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.
-
If
DELETE
is specified, the range
of line numbers is deleted from the
existing code before the merge. This is pointless without MERGE
.
Parameters
-
The string expression
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.
Notes
-
CHAIN
preserves the OPTION BASE
setting.
-
Only if
ALL
is specified, DEF FN
definitions are preserved.
-
Only if
MERGE
is specified, DEFINT
, DEFSTR
, DEFSNG
, DEFDBL
definitions
are preserved.
-
If specified,
ALL
must precede DELETE
; if unspecified, no comma must
be put in its place and only two commas should precede DELETE
.
Errors
-
file_spec
has a numeric value: Type mismatch.
-
file_spec
contains disallowed characters:
Bad file number (on CAS1:
);
Bad file name (on disk devices).
-
The file specified in
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.
-
A line number in
range
is greater than 65529: Syntax error.
-
If a Syntax error is raised by
CHAIN
, no lines are deleted and the new
program is not loaded.
-
The closing line number in
range
does not exist: Illegal function call
-
If
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.
-
A loaded text file contains lines without line numbers:
Direct statement in file.
-
A loaded text file contains lines longer than 255 characters:
Line buffer overflow.
Attempting to load a text file that has
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.
Parameters
-
The string expression
dir_spec
is a
valid file specification indicating an existing
directory on a disk device.
Errors
-
No matching path is found: Path not found.
-
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.
Parameters
-
The midpoint of the ellipse is at
(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.
-
If
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.
Notes
-
For
aspect <> 1
, the midpoint algorithm used does not pixel-perfectly
reproduce GW-BASIC's ellipses.
Errors
-
The statement is executed in text mode: Illegal function call.
-
start
or end
is not in [0—2π]
: Illegal function call.
-
The statement ends with a comma: Missing operand.
CLEAR
CLEAR [expr] [, [mem_limit] [, [stack_size] [, video_memory]]]
Clears all variables, arrays,DEF FN
user functions and DEFtype
type definitions.
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.
Parameters
-
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.
Notes
-
The purpose of
expr
is unknown.
-
If called inside a
FOR
—NEXT
or
WHILE
—WEND
loop, an error will be raised at
the NEXT
or WEND
statement, since the loop stacks have been cleared.
Errors
-
Any of the arguments has a string value: Type mismatch.
-
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.
Parameters
-
file_1, file_2, ...
are numeric expressions yielding
file numbers.
Notes
-
No error is raised if the specified file numbers were not open.
Errors
-
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.
-
The statement ends in a comma, Missing operand.
-
If an error occurs, only the files before the erratic value are closed.
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.
Parameters
x
is a numeric valued expression.
-
If
x = 0
, the whole screen is cleared.
-
If
x = 1
, the graphics view region is cleared.
-
If
x = 2
, the text view region is cleared.
The optional argument x
is not available with
syntax={pcjr|tandy}
.
Errors
-
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.
-
No comma is specified but more text follows: Illegal function call.
-
A comma is specified followed by more: Syntax error.
-
syntax=pcjr
is set
and an argument is specified: Syntax error.
-
syntax=tandy
is set
and an argument is specified: Illegal function call.
-
If an error occurs, the screen is not cleared.
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.
Parameters
-
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.
Textmode attributes (colour)
Textmode attributes (monochrome)
Notes
Errors
-
Any of the parameters has a string value: Type mismatch.
-
Any of the parameters is not in
[-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.
-
Statement is used in
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).
All pixels with attributes 1,2,3 will change colour to the new palette.
-
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.
CGA palettes
Notes
Errors
-
Any of the parameters has a string value: Type mismatch.
-
Any of the parameters is not in
[-32768—32767]
: Overflow.
-
Any of the parameters is not in
[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.
Parameters
-
foreground
is a numeric expression in [1—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.
EGA default palette
EGA colour list
Notes
Errors
-
Any of the parameters has a string value: Type mismatch.
-
Any of the parameters is not in
[-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.
Parameters
-
port
is a numeric expression with a value of 1
or 2
. This specifies which
serial port (COM1:
or COM2:
) is trapped. If port
equals 0
, this statement does nothing.
Errors
-
port
a string value: Type mismatch.
-
port
is not in [-32768—32767]
: Overflow.
-
port
is not in [0—3]
: Illegal function call.
COMMON
COMMON [var_0 [( [index_0] )] [, [var_1 [( [index_1] )] ]] ...]
Specifies variables to be passed as common variables to the program called
with CHAIN
.
Parameters
-
var_0, var_1, ...
are names of scalar or array variables.
-
index_0, index_1, ...
are optional number literals; they are ignored.
Notes
-
Array elements with square brackets and an index do not cause an error, but are ignored.
-
COMMON
statements are not executed during run time; rather, when a CHAIN
command is encountered where ALL
is not specified,
all COMMON
declarations in the program are parsed. As a consequence, the DEFSTR
, DEFINT
, DEFSNG
or DEFDBL
settings
used are those that are active at the time of execution of the CHAIN
statement.
-
COMMON
declarations need not be reachable in the program flow in order to be used.
They may occur anywhere before or after the CHAIN
statement that uses them.
-
Variables may be repeated or occur in multiple
COMMON
declarations.
-
If the
COMMON
keyword is not the first element of the statement, the
declaration will be ignored. In particular, any COMMON
declaration that occurs
directly after a THEN
or ELSE
keyword will not be used. COMMON
in the second or later statements of a compound statement after THEN
or ELSE
will be used regardless of the value of the IF
condition.
CONT
CONT [anything]
Resumes execution of a program that has been halted by
STOP
, END
,
Ctrl+C, or Ctrl+Break.
If run from a program, stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
Notes
-
Anything after the
CONT
keyword is ignored.
-
This statement can only be used in direct mode.
-
If a break is encountered in
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.
Errors
-
No program is loaded, a program has not been run, after a program line
has been modified or after
CLEAR
: Can't continue.
-
The break occurred in a direct line: 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.
Parameters
-
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.
Notes
-
DATA
declarations need not be reachable in the program flow in order to be used.
They may occur anywhere before or after the READ
statement that uses them.
-
If the
DATA
keyword is not the first element of the statement, the
declaration will be ignored. In particular, any DATA
declaration that occurs
directly after a THEN
or ELSE
keyword will not be used. DATA
in the second or later statements of a compound statement after THEN
or ELSE
will be used regardless of the value of the IF
condition.
Errors
-
If the type of the literal does not match that of the corresponding
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{-|/}yy"
or
"mm{-|/}dd{-|/}yyyy"
Of these,
-
mm
may be one or two characters long and must be in [1—12]
.
-
dd
may be one or two characters long and must be in [1—31]
.
-
yyyy
must be in [1980—2099]
.
-
yy
may be one or two characters long and must be in one of the ranges:
-
[0—77]
, interpreted as 2000—2077
; or
-
[80—99]
, interpreted as 1980—1999
.
Notes
-
The system date is not actually changed; rather, PC-BASIC remembers the
offset from the true system date. This avoids requiring user permission
to change the system time.
-
GW-BASIC appears to accept invalid dates such as
"02-31-2000"
. PC-BASIC
raises Illegal function call for these.
Errors
-
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
.
Notes
-
This statement may only be used on a program line.
-
As the function must be a single expression and PC-BASIC does not have a ternary operator, there is
no way to define a recursive function that actually terminates.
Parameters
-
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.
Errors
-
The statement is executed directly instead of in a program line: Illegal direct.
-
If the type of the return value is incompatible with the type of
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
- integer (
%
)
DEFDBL
- double (
#
)
DEFSNG
- single (
!
)
DEFSTR
- string (
$
)
Parameters
-
first_0, last_0, ...
are letters of the alphabet.
Pairs of letters connected by a dash -
indicate inclusive ranges.
Notes
-
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
.
Parameters
-
address
is a numeric expression in [-32768—65535]
.
Notes
-
If
address
is negative, it is interpreted as its two's complement.
-
If
address
is not specified, the segment is set to the GW-BASIC data
segment.
Errors
-
address
has a string value: Type mismatch.
-
address
is not in [-32768—65535]
: Overflow.
DEF USR
DEF USR[n] = address
Does nothing.
Parameters
-
n
is a digit between 0 and 9 inclusive.
-
address
is a numeric expression in [-32768—65535]
.
Notes
-
In GW-BASIC, this statement sets the starting address of an assembly-language function.
-
This statement is not implemented in PC-BASIC.
-
If
address
is negative, it is interpreted as its two's complement.
Errors
-
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. Any further statements on the line will be ignored, also in direct mode.
Parameters
-
line_number_0
and
line_number_1
are line numbers in the range [0—65529]
, specifying the inclusive range of line numbers to delete.
-
A
.
indicates the last line edited.
-
If the start point is omitted, the range will start at the start of the program.
-
If the end point is omitted, the range will end at the end of the program.
-
If no range is specified, the whole program will be deleted.
Errors
-
line_number_0
or
line_number_1
is greater than 65529
: Syntax error.
-
The range specified does not include any program lines stored: Illegal function call.
DIM
DIM name [{(|[} limit_0 [, limit_1] ... {)|]}] [, ... ]
Allocates memory for one or more 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.
A DIM
entry with no brackets and no indices performs no operation. Empty brackets are not allowed.
The least index allowed is determined by OPTION BASE
.
Parameters
-
name, ...
are legal variable names
specifying the arrays to be allocated.
-
limit_0, limit_1, ...
are numeric
expressions that specify the greatest index allowed at that position.
Notes
-
Mixed brackets are allowed.
-
The size of arrays is limited by the available BASIC memory.
-
The maximum number of indices is, theoretically,
255
. In practice,
it is limited by the 255-byte limit on the length of program lines.
Errors
-
name
has already been dimensioned: Duplicate definition.
-
An index is empty: Syntax error.
-
An index is missing at the end: Missing operand.
-
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.
-
The array exceeds the size of available variable
space: Out of memory.
DRAW
DRAW gml_string
Draws the shape specified by gml_string
,
a string expression in Graphics Macro Language (GML).
Graphics Macro Language reference
- Movement commands
-
[B][N] movement
where the default is to move and draw; the optional prefixes mean:
and movement
is one of:
where n
is an integer in [-32768—32767]
and
x
, y
are integers in [0—9999]
.
Where optional, n
defaults to 1
.
- Scale commands
-
- Colour commands
-
- Subroutine command
-
s
is one of the following:
- a string variable name followed by semicolon (
;
)
- the result of
VARPTR$()
on a string variable
Numeric variables n
, x
,
y
, b
in the commands above can be:
-
an integer literal, e.g.
DRAW "U100"
-
a numeric variable name or array element
var
preceded by =
and followed by ;
.
For example, DRAW "U=VAR;"
or DRAW "U=A(1);"
-
the result of
VARPTR$(var)
preceded by =
. For example, DRAW "U=" + VARPTR$(VAR)
Notes
-
The
CLS
statement resets the step size to 1 pixel, angle to 0 degrees and position to the
centre of the view region.
-
The value
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
.
-
In GW-BASIC, the numeric arguments of
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.
Errors
-
gml_string
has a numeric value: Type mismatch.
-
gml_string
has errors in the GML: Illegal function call.
-
A variable referenced in the GML string is of incorrect type: Type mismatch.
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.
Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
Errors
-
No line_number is specified: Undefined line number.
-
More characters are written after the line number: Illegal function call.
-
line_number
is not in [0—65529]
: Illegal function call.
-
The specified line number does not exist: Undefined line number.
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.
Parameters
command_string
is a string expression of one of the following forms:
-
"VARIABLE=VALUE"
-
to set
VARIABLE
to VALUE
;
-
"VARIABLE="
-
to unset
VARIABLE
.
VARIABLE
must be an
ASCII string and will be converted to uppercase on case-sensitive systems.
Errors
-
command_string
has a numeric value: Type mismatch.
-
command_string
is not of the required form: Illegal function call.
-
VARIABLE
contains characters outside of ASCII: Illegal function call.
ERASE
ERASE array_0 [, array_1] ...
De-allocates arrays. The data stored in the
arrays is lost.
Parameters
-
array_0, array_1 ...
are names of existing arrays. The names must be
specified without brackets.
Errors
-
No array names are given: Syntax error.
-
array_0, array_1 ...
do not exist: Illegal function call.
-
If an error occurs, the arrays named before the error occurred are erased.
ERROR
ERROR error_number
Raises the error with number error_number
.
See the list of error numbers and messages.
Parameters
-
error_number
is an expression
with a numeric value.
Errors
-
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.
Notes
-
A
FIELD
statement
without any variables specified has no effect.
-
Another
FIELD
statement on the same file will specify an alternative mapping of the
same file buffer; all mappings will be in effect simultaneously.
-
A subsequent assignment or
LET
or MID$
statement on name_0 , name_1 ...
will dis-
associate the string variable from the field buffer.
-
Use
LSET
, RSET
or
MID$
to copy values into a FIELD
buffer.
-
Use
GET
to read values from the file into the field
buffer, changing the variables.
-
Use
PUT
to write the field buffer to the file.
Parameters
-
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.
Errors
-
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.
-
The statement ends in a comma: Missing operand.
-
No file number is specified: Missing operand.
-
The lengths in a
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.
Parameters
-
filter_spec
is a string expression that
is much like a file specification, but optionally allows the file
name part to contain wildcards.
Notes
-
The filename filter may contain the following wildcards:
-
The filter
will only match MS-DOS style filenames.
-
Matched character series do not stretch across directory separators
\
or extension separators .
. To match all files with all extensions,
use *.*
.
-
Alternatively, if all files in a
specified directory are required, end the directory name with a backslash
\
.
Errors
-
filter_spec
has a numeric value: Type mismatch.
-
filter_spec
is the empty string: Bad file name.
-
The specified filter does not match any files: File not found.
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.
start
, stop
and step
are evaluated only once and the resulting
values are used throughout the loop.
Parameters
-
loop_var
is an integer or single-precision variable.
-
start
, stop
and step
are numeric expressions.
Errors
-
No
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 a double-precision variable:
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
.
Parameters
-
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.
Notes
-
If the record number is beyond the end of the file, the file buffer is
filled with null bytes.
-
The record number is stored as single-precision; this precision is not high enough to distinguish single
records near the maximum value of
2^25
.
Errors
-
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 mode.
-
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
.
Parameters
-
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.
Notes
-
If
bytes
is 32768
or greater, GW-BASIC hangs. This functionality is not implemented in PC-BASIC.
-
In GW-BASIC, Device I/O error is raised for overrun error, framing error,
and break interrupt. Device fault is raised if DSR is lost during I/O.
Parity error is raised if parity is enabled and incorrect parity is
encountered. This is according to the manual; it is untested.
Errors
-
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.
-
If the serial input buffer is full, i.e.
LOF(com_file_number) = 0
, and
LOC(com_file_number) = 255
: Communication buffer overflow
-
If the carrier drops during
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:
Parameters
-
array_name
is the name of a numeric array dimensioned with enough space to store the area.
-
x0
, y0
, x1
, y1
are numeric expressions.
Notes
-
In PCjr/Tandy mode, in
SCREEN 6
, GET
stores an area of twice the width
of the specified rectangle.
Errors
-
The array does not exist: Illegal function call.
-
array_name
refers to a string array: Type mismatch.
-
The area is too large for the array: Illegal function call.
-
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.
Parameters
-
line_number
is an existing line number literal.
-
Further characters on
the line are ignored until end of statement.
Notes
-
If no
RETURN
is encountered, no problem.
-
One optional space is allowed between
GO
and SUB
; it will not be retained in
the program.
Errors
-
If
line_number
does not exist: Undefined line number.
-
If
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.
Parameters
-
line_number
is an existing line number literal.
-
Further characters on
the line are ignored until end of statement.
Notes
-
Any number of optional spaces is allowed between
GO
and TO
, but they will
not be retained in the program.
-
If
line_number
is greater than 65529
, only the first 4 characters are
read (e.g. GOTO 65530
is executed as GOTO 6553
)
Errors
-
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
.
Parameters
-
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.
Notes
-
The comma is optional and ignored.
-
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.
-
All clauses must be on the same
program line.
-
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.
-
As in
GOTO
, anything after the line number is ignored.
Errors
-
If
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 [;] [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.
Parameters
-
prompt
is a string literal.
-
var_0, var_1, ...
are variable names or fully indexed array elements.
Notes
-
Values entered must be separated by commas. Leading and trailing whitespace
is discarded.
-
String values can be entered with or without double quotes (
"
).
-
If a string with a comma, leading or trailing whitespace is needed,
quotes are the only way to enter it.
-
Between a closing quote and the comma at the end of the entry, only white-
space is allowed.
-
If quotes are needed in the string itself, the first character must be
neither a quote nor whitespace. It is not possible to enter a string that
starts with a quote through
INPUT
.
-
If a given
var_n
is a numeric variable, the value entered must be
number literal.
-
Characters beyond the 255th character of the screen line are discarded.
-
If user input is interrupted by Ctrl+Break,
CONT
will re-execute the
INPUT
statement.
Errors
-
If the value entered for a numeric variable is not a valid numeric literal,
or the number of values entered does not match the number of variables in
the statement,
?Redo from start is printed and all values must be entered again.
-
A Syntax error that is caused after the prompt is printed is only raised
after the value shave been entered. No values are stored.
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.
Parameters
-
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.
Notes
-
The
#
is mandatory. There may or may not be whitespace between INPUT
and #
.
-
String values can be entered with or without double quotes (
"
).
-
Numeric values are terminated by
, LF
, CR
, ,
.
-
Unquoted strings are terminated by
LF
, CR
, ,
.
-
Quoted strings are terminated by the closing quote.
-
Any entry is terminated by
EOF
character or its 255th character.
-
Leading and trailing whitespace is discarded.
-
If the entry cannot be converted to the requested type, a zero value is
returned.
-
If
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)
.
Errors
-
Input is requested after the end of a text file has been reached or an
EOF
character has been encountered: Input past end.
-
The last character of the field buffer is read: Field overflow.
-
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.
Notes
-
In GW-BASIC,
IOCTL
sends a control string to a device.
-
This statement is not implemented in PC-BASIC.
Errors
-
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.
-
Otherwise: Illegal function call
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.
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.
Parameters
-
key_id
is a numeric expression in the range
[1—12]
(or [1—10]
when syntax=gwbasic
).
-
string_value
is a string expression.
Notes
-
If
key_id
is not in the prescribed range,
the statement is interpreted as an
event-trapping KEY
statement.
-
If
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.
Errors
-
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.
Event trapping can only be active during execution of a program, it does not work in direct mode.
Parameters
key_id
is a numeric expression in [1—20]
.
Keys are:
Keys 15 to 25 are defined using the event trapping
KEY
definition statement.
Notes
-
With
syntax=tandy
, key 11
is F11 and key 12 is F12.
Pre-defined keys 11—14 shift to 13—16.
Errors
-
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
.
Parameters
-
key_id
is a numeric
expression in [15—25]
(or [15—20]
when syntax=gwbasic
, 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:
For the unmodified key, the modifier character is CHR$(0)
.
Notes
-
If
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.
-
If
key_id
is in [1—10]
(or [1—12]
when syntax=tandy
),
the statement is interpreted as a
function-key macro definition.
-
The extended modifier
&h80
refers to the additional keys
that were introduced with the Model M 101-key keyboard in th earea between the main
keyboard and the numerical keypad. These are the arrow keys,
Home, End, PgUp, PgDn, Ins,
Del as separate from the numerical keypad.
PC-BASIC ignores this modifier; in a key definition, it does not make a difference
whether or not it is set.
Errors
-
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 filter_spec
Deletes one or more files on a disk device.
Parameters
-
The string expression
filter_spec
is a
valid file specification indicating the files to delete.
Wildcards are allowed. See FILES
for a description
of wildcards.
Notes
-
Be very careful with the use of wildcards in this statement: the DOS matching rules may
not be the same as what is usual on your operating system, which could result in
unexpected files being deleted.
-
This statement may not delete hidden file and files that do not have short names
which are legal DOS names. However, this behaviour is not guaranteed
so you must not depend on it.
Errors
-
filter_spec
is a numeric value: Type mismatch.
-
A file with a base name equal to that of a file matching
filter_spec
is open: File already open
-
No file matches
filter_spec
: File not found
-
The user has no write permission: Permission denied
-
If a syntax error occurs after the closing quote, the file is removed anyway.
LCOPY
LCOPY [num]
Does nothing.
Parameters
-
num
is a numeric expression in [0—255]
.
Notes
-
This statement does nothing in GW-BASIC. Presumably, it is left over from a
statement in older versions of MS Basic that would copy the screen to the
printer.
Errors
-
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
.
Parameters
-
name
is a variable that may or may not already exist.
-
The
type of
expression
matches that of name
: that is, all numeric types can
be assigned to each other but strings can only be assigned to strings.
Errors
-
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.
Parameters
-
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.
Notes
-
If a coordinate is outside the screen boundary, it is replaced with -1 (if
less than 0) or the screen dimension (if larger than the screen dimension).
Errors
-
The statement ends in a comma and it is the first or third: Missing operand. If it is the second: Syntax error.
-
Any of the coordinates is not in
[-32768—32767]
: Overflow.
-
Any of the parameters has a string value: Type mismatch.
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.
Parameters
-
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.
Notes
-
If user input is interrupted by Ctrl+Break,
CONT
will re-execute the LINE
INPUT
statement.
-
Unlike
INPUT
, LINE INPUT
does not end the prompt with ?
.
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.
Parameters
-
string_name
is a string variable or array element.
Notes
-
The
#
is mandatory. There may or may not be whitespace between INPUT
and #
.
-
Input is only terminated by a
CR
.
-
If
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)
.
Errors
-
Input is requested after the end of a text file has been reached or an
EOF
char has been encountered: Input past end.
-
The last character of the field buffer is read: Field overflow.
-
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.
Notes
-
In GW-BASIC 3.23,
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
hide-listing=65530
.
Parameters
-
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.
-
The string expression
file_spec
is a
valid file specification indicating the file to list to.
If this file already exists, it will be overwritten.
Errors
-
A line number is greater than
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 line printer LPT1:
, 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.
Notes
-
In GW-BASIC 3.23,
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
hide-listing=65530
.
Parameters
-
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.
Errors
-
A line number is greater than
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
CLEAR
.
Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
If ,R
is specified, keeps all data files open and runs the specified file.
Parameters
-
The string expression
file_spec
is a valid file specification indicating
the file to read the program from.
Errors
-
file_spec
has a numeric value: Type mismatch.
-
file_spec
contains disallowed characters:
Bad file number (on CAS1:
);
Bad file name (on disk devices).
-
The file specified in
file_spec
cannot be found: File not found.
-
A loaded text file contains lines without line numbers:
Direct statement in file.
-
A loaded text file contains lines longer than 255 characters:
Line buffer overflow.
Attempting to load a text file that has
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.
Notes
-
On emulated VGA cards, the cursor shape parameters are interpreted
in a complicated way that is intended to maintain functional compatibility with CGA.
-
In GW-BASIC, cursor shape is preserved after pressing Ins twice. The insert-mode cursor is different from the usual half-block.
In PC-BASIC, insert mode resets the cursor shape to default.
-
Cursor shape and visibility options have no effect in graphics mode.
-
Locate accepts a 5th comma at the end, which is ignored.
Errors
-
Any parameter has a string value: Type mismatch.
-
Any parameter is not in
[-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.
Parameters
-
file_number
is a numeric expression in [0—255]
.
-
record_0
and record_1
are numeric expressions in [1—2^25-2]
.
Notes
-
In GW-BASIC under MS-DOS, the
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.
-
If
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.
-
To check if another open file is the same file, PC-BASIC only looks at the base name
of the file, i.e. its DOS name without directories. As a consequence, if a file "test.txt"
is open and locked, an attempt to lock a file "dir\test.txt" will fail, even if these are
different files. Conversely, if two file names are different but point to the same file in the
file system (for example due to file system links), then these will be considered as different files by BASIC.
Errors
-
Any parameter 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.
-
LOCK
(part of) a file with the same name as a file already locked: Permission denied.
-
record_0
or record_1
is not in [1—2^25-2]
: Bad record number.
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.
Parameters
-
string_name
is a string variable or array element.
expression
is a string expression.
Notes
-
If
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.
-
If
string_name
has not been allocated before, this statement has no effect.
-
Use
LSET
, RSET
or
MID$
to copy values into a FIELD
buffer.
-
If
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.
Errors
-
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.
Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
Parameters
-
The string expression
file_spec
is a valid file specification indicating
the file to read the program from.
Errors
-
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.
-
A loaded text file contains lines without line numbers:
Direct statement in file.
-
A loaded text file contains lines longer than 255 characters:
Line buffer overflow.
Attempting to load a text file that has
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
.
Parameters
-
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]
.
Notes
-
No whitespace is allowed between
MID$
and (
.
-
If
substring
is longer than length
, only the first length
characters
are used.
-
If
substring
is shorter than length
, only LEN(substring)
characters
are replaced.
Errors
-
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.
Parameters
-
The string expression
dir_spec
is a valid
file specification that specifies the
path of the new directory on a disk device.
Errors
-
dir_spec
is not a string: Type mismatch.
-
The parent directory does not exist: Path not found.
-
The directory name already exists on that path: Path/File access error.
-
The user has no write permission: Permission denied.
MOTOR
MOTOR [num]
Does nothing.
Parameters
-
num
is a numeric expression in [0—255]
.
Notes
-
In GW-BASIC, this statement turns on the cassette motor if
num
is nonzero or omitted, and turns it off if num
is zero. This is not implemented in PC-BASIC.
Errors
-
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
.
Parameters
-
The string expressions
old_name
and new_name
are valid file specifications giving the path on a disk device to the old and new filenames,
respectively.
Notes
Errors
-
old_name
or new_name
have number values: Type mismatch.
-
old_name
does not exist: File not found.
-
A file with a base name equal to that of
old_name
or new_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.
Parameters
-
var_0, var_1, ...
are numeric variables which are loop counters in a FOR
statement.
Errors
-
No
FOR
statement is found to match the NEXT
statement and variables:
NEXT without FOR.
-
var_0, var_1, ...
are string variables: NEXT without FOR.
-
The (implicit or explicit) loop variable is an integer variable and is
taken outside the range
[-32768, 32767]
when incremented after the final iteration: Overflow .
NOISE
NOISE source, volume, duration
Generates various kinds of noise.
Parameters
-
source
is a numeric expression in [0—7]
.
It indicates the type of noise:
-
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.
Notes
-
This statement is only available if
syntax={pcjr|tandy}
is set.
Errors
-
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.
Parameters
-
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.
Errors
-
n
has a string value: Type mismatch.
-
n
is not in [-32768—32767]
, Overflow .
-
n
is not in [0—255]
: Illegal function call.
-
The line number jumped to does not exist: Undefined line number.
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:
Notes
Errors
-
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.
Parameters
-
line_number
is an existing line number in the program.
Notes
-
It is not possible to start the error handler at line number
0
.
Errors
-
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.
Parameters
-
The string expression
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"]
.
Access modes
The FOR
modes or mode_char
are as follows:
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:
Sharing and locks
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
OPEN "file" ACCESS acc_2 SHARED AS 2
the following combinations are allowed:
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.
To check if another open file is the same file, PC-BASIC only looks at the base name
of the file, i.e. its DOS name without directories. As a consequence, if a file "test.txt"
is open and locked, an attempt to lock a file "dir\test.txt" will fail, even if these are
different files. Conversely, if two file names are different but point to the same file in the
file system (for example due to file system links), then these will be considered as different files by BASIC.
File specifications
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.
-
Disk devices
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.
If the file name provided does not contain any dots, the LOAD
,
SAVE
,
BLOAD
,
BSAVE
,
CHAIN
,
MERGE
,
RUN
, and
LIST
statements
append the default
extension .BAS
. To refer
to a file name without an extension, the file specification should
end in a dot .
. For other statements, appending a dot is allowed but not required.
Compatibility notes
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.
In order to allow access to files whose name on the host system does
not conform to DOS standards while maintaining compatibility with GW-BASIC,
PC-BASIC will follow these steps to match DOS-style file names to host file names:
-
Look for a file with the name as provided.
This can be a long file name which may contain non-permissible characters and which will be case sensitive if
your file system is.
-
If such a file is not found, it will truncate the name
provided to all-uppercase 8.3 format and look for an exact match.
The truncated name consists of the first 8 characters before the first dot,
followed by the first three characters after the first dot.
If the resulting file name contains non-permissible characters, an error will be raised.
-
Look for 8.3 names in mixed case which match the name
provided in a case-insensitive way. Such files are searched in lexicographic
order. File names longer than 8.3 will not be matched, unless their name is entered exactly.
On Windows, the name matched can be a short filename as well as a
long filename provided it is of 8.3 length — it may, for example, contain
spaces and thus not be a valid Windows short file name.
If the file name provided ends in a single dot and contains no other dots,
PC-BASIC will first match the name as provided; if this is not found, it will match
the name as provided but without the single dot. The 8.3 format of such a file name will match
file names with and without the dot, in lexicographic order.
If no matching file is found for an output file name, a new file will be
created with an all-uppercase 8.3 file name.
-
Cassette device
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:
- A
- Program file in text format
- B
- Program file in tokenised format
- D
- Data file
- M
BSAVE
memory image
- P
- Program file in protected format
If the file does not match the file specification and required file type,
the status is Skipped; if the file matches, the status is
Found. When called from a program, these statements do
not print messages to the console.
If the device
was specified explicitly,
parameters
may also be empty. In this case the
first file of the appropriate type is opened.
-
Console and parallel devices
SCRN:
, KYBD:
, and LPTn:
-
These devices do not allow further device parameters.
-
Serial devices
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:
Notes
-
If a
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.
-
For
INPUT
, OUTPUT
and APPEND
modes, LEN
may be specified but is ignored.
-
If I/O is attempted contravening the
FOR
mode specified,
the PRINT
or
INPUT
statement will raise Bad file mode.
-
If
RANDOM
I/O is attempted contravening the ACCESS
mode specified, the
PUT
or GET
statement will raise Path/File access error.
-
The
#
is optional and has no effect.
Errors
-
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.
-
The
COM:
file_spec
parameters do not follow the specification:
Bad file name.
-
The
CAS1:
file_spec
contains disallowed characters:
Bad file number.
-
A file with the same name is already open for
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
.
Parameters
-
n
is a literal digit 0
or 1
. Expressions are not allowed.
Notes
-
If
OPTION BASE
has not been called,
the first array allocation defaults to starting index 0.
Errors
-
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:
Notes
-
Only a limited number of machine ports are emulated.
-
In GW-BASIC under MS-DOS, the sequence needed to set the colour plane mask is:
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.
Parameters
-
port
is a numeric expression in [-32768—65535]
.
-
value
is a numeric expression in [0—255]
.
Errors
-
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.
Parameters
-
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.
-
If
attrib
has a number value, it must be in [0—255]
; it specifies the colour
attribute used to fill.
-
If
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).
Tile patterns
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.
-
1 bit per pixel (e.g.
SCREEN 2
)
- Here is an example:
76543210
|
Byte value
|
*.......
|
&h80
|
.*......
|
&h40
|
..*.....
|
&h20
|
...*....
|
&h10
|
....*...
|
&h08
|
.....*..
|
&h04
|
......*.
|
&h02
|
This diagonal stripe pattern can thus be produced with
PAINT (0, 0), CHR$(128)+CHR$(64)+CHR$(32)+CHR$(16)+CHR$(8)+CHR$(4)+CHR$(2)
-
SCREEN 7
, 8
, 9
-
The tile pattern is always 8 pixels wide. The first character in the
pattern string contains the first bit of each of these 8 pixels, the
second character contains the second bits, etc.
For example, in a 2-bits-per-pixel mode, four colour attributes can be used in the pattern.
To create a diagonal stripe pattern of the same shape, in attribute
&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
|
If the pattern string is truncated before all bits of the last line
have been defined, the remaining bits will be zero.
-
SCREEN 1
, 3
, 4
, 5
, 6
-
Each row of the tile pattern represents a screen row. Colours are
encoded in consecutive bits; the more bits per pixel, the narrower the
pattern is. For 2 bits per pixel, the pattern is 4 pixels wide; for 4
bits per pixel it is 2 pixels wide. The following pattern string encodes
a diagonal dotted stripe in two colours:
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.
Boundaries
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.
The background tile pattern is constructed just like the tile pattern. However, only
the first row of the background tile is taken into account; the rest is ignored.
The background tile must not match the attribute tile, or more than two consecutive rows of it.
Errors
-
If more than two consecutive rows of the attribute tile (or all rows, if there are less than three)
equal the first row of the background tile: 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.
Parameters
-
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.
Errors
-
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.
Parameters
-
int_array_name
is a single- or multidimensional
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.
Notes
-
Array values are assigned to palette entries in the order in which they are stored in memory.
See Arrays for details about the layout of arrays in memory.
-
If an array entry has value
-1
, the matching attribute is left unchanged.
Errors
-
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
.
Parameters
-
src
and dst
are numeric expressions between 0 and the current video
mode's number of pages, less one.
Errors
-
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.
Parameters
-
mml_string_0
, mml_string_1
, mml_string_2
are string expressions in MML.
-
At least one parameter must be provided and the statement must not end in a comma.
Music Macro Language reference
Notes and Pauses
Timing commands
Background-mode commands
These commands affect SOUND
,
PLAY
and BEEP
Subroutine command
Volume control
Volume control is available on syntax={tandy | pcjr}
only:
MML Parameters
Numeric variables n
in the commands above can be:
-
an integer literal, e.g.
PLAY "L4G"
-
a numeric variable name or array element
var
preceded by =
and followed by ;
.
For example, PLAY "L=VAR;G"
or PLAY "L=A(1);G"
-
the result of
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.
Commands may optionally be separated by one semicolon ;
, but not by more than one.
Errors
-
mml_string
has a numeric value: Type mismatch.
-
mml_string
has errors in the MML: Illegal function call.
-
A variable in an MML string is of incorrect type: Type mismatch.
-
No MML string is specified: Missing operand.
-
If
SOUND ON
has not been executed, using the three-voice syntax
will raise Syntax error.
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
.
Parameters
-
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]
.
Notes
-
The memory is only partly emulated in PC-BASIC. See Memory model for supported addresses.
Outside emulated areas of memory, this statement has no effect.
Errors
-
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.
Parameters
-
x
, y
are numeric expressions in [-32768—32767]
.
-
attrib
is a numeric expression in [0—255]
.
Errors
-
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.
Expressions can optionally be separated by one or more of the following keywords:
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.
Format string syntax
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.
For string expressions:
For numeric expressions, the format string specifies a width and alignment.
The number of characters in the field must not exceed 24.
Tokens preceding the number field:
Tokens trailing the number field:
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.
-
If there are more expressions than format fields, the format string is
wrapped around.
-
Expressions may be separated with semicolons or commas; the effect is the
same.
-
If the
USING
declaration ends in a comma or semicolon, no newline is printed at
the end.
-
After a
USING
declaration, other elements of the PRINT
syntax such as SPC(
and TAB(
can not
be used.
Parameters
-
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.
Notes
-
If an error is raised, the output before the error was encountered is
printed as normal.
-
In GW-BASIC, when formatting a number with a dollar sign, if the number is in the range
[-10000—-32767]
and does not fit in the width of the number field,
the minus sign is omitted. This is not implemented in PC-BASIC.
Errors
-
n
has a string value: Type mismatch.
-
n
is not in [-32768—65535]
: Overflow.
-
The format string contains no tokens: Illegal function call.
-
An expression doesn't match the corresponding format token type: Type mismatch.
-
A number field in the format string exceeds 24 characters: Illegal function call.
-
A number field in the format string contains no
#
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
.
Parameters
-
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.
Notes
-
The record number is stored as single-precision; this precision is not high enough to distinguish single
records near the maximum value of
2^25
.
Errors
-
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 mode.
-
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.
Notes
-
In GW-BASIC, Device I/O error is raised for overrun error, framing error,
and break interrupt. Device fault is raised if DSR is lost during I/O. A
Parity error is raised if parity is enabled and incorrect parity is
encountered. This is according to the manual; it is untested.
Errors
-
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.
-
The serial input buffer is full, i.e.
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:
Parameters
-
array_name
is a numeric array.
-
x0
, y0
are numeric expressions.
Errors
-
The array does not exist: Illegal function call.
-
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.
Parameters
-
expr
is a numeric expression.
Notes
-
For the same seed, PC-BASIC produces the same pseudorandom numbers as
GW-BASIC 3.23.
-
The random number generator is very poor and should not be used for serious purposes.
See
RND
for details.
Errors
-
expr
has a string value: Illegal function call.
-
The user provides a seed outside
[-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.
Parameters
-
var_0
, var_1
are variables or array elements.
Errors
-
Not enough data is present in
DATA
statements: Out of DATA.
-
The type of the variable is not compatible with that of the data entry
being read: a Syntax error occurs on the
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.
Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
Notes
-
Line numbers afer the following keywords will be renumbered:
AUTO
, EDIT
,
ELSE
, ERL
,
DELETE
, GOSUB
,
GOTO
, LIST
,
LLIST
, RENUM
,
RESTORE
, RESUME
,
RETURN
, RUN
,
THEN
.
-
Any line numbers in
CHAIN
statements will not be
renumbered; note that these line numbers refer to another program.
-
All arguments of
RENUM
or AUTO
statements in a program will be renumbered,
including any line number offsets or increments, even though that does not make much sense.
-
A zero line number following the keywords
ERROR GOTO
will not be renumbered.
-
If a referenced line number does not exist in the program, a
message Undefined line ref in old_line
is printed. Here,
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.
Errors
-
Any of the parameters is not in
[0—65529]
: Syntax error.
-
Any of the newly generated line numbers is greater than
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.
Notes
-
Official GW-BASIC documentation and many other sources state that
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
.
Errors
-
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.
Errors
-
RESUME
is encountered outside of an error trapping routine:
RESUME without error.
-
The program ends inside an error trapping routine without a
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.
Errors
-
line
is not an existing line number: Undefined line number.
RMDIR
RMDIR dir_spec
Removes an empty directory on a disk device.
Parameters
-
The string expression
dir_spec
is a
valid file specification that specifies the path and name of the directory.
Errors
-
dir_spec
has a numeric value: Type mismatch.
-
dir_spec
is an empty string: Bad file name.
-
No matching path is found: Path not found.
-
Directory to remove is not empty: Path/File access error.
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.
Parameters
-
string_name
is a string variable or array element.
expression
is a string expression.
Notes
-
If
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.
-
If
string_name
has not been allocated before, this statement has no effect.
-
Use
LSET
, RSET
or
MID$
to copy values into a FIELD
buffer.
-
If
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.
Errors
-
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. RUN
implies CLEAR
.
If file_spec
is given, any program in memory will be erased.
If ,R
is specified after file_spec
, files are kept open; if not, all files are closed.
Parameters
-
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.
-
The string expression
file_spec
, if specified,
is a valid file specification indicating
the file to read the program from.
Errors
-
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.
-
A loaded text file contains lines without line numbers:
Direct statement in file.
SAVE
SAVE file_spec [, {A|P}]
Stores the current program in a file.
-
If
,A
is specified, the program will be saved in plain text format.
In this case, program execution will stop and control will be returned to the user.
Any further statements on teh line will be ignored, also in direct mode.
-
If
,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.
-
If neither is specified, the program will be saved in tokenised format.
Parameters
-
The string expression
file_spec
is a valid file specification
indicating the file to store to.
Errors
-
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).
-
hide-protected
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.
Parameters
-
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.
Video modes
The video modes are as follows:
SCREEN 0
Text mode
-
80x25 or 40x25 characters of 8x16 pixels
16 attributes picked from 64 colours
Attributes 16-31 are blinking versions of 0-15
4 pages ega
SCREEN 1
CGA colour
-
320x200 pixels
40x25 characters of 8x8 pixels
4 attributes picked from 16 colours; 2 bits per pixel
1 page ega
2 pages pcjr
tandy
SCREEN 2
CGA monochrome
-
640x200 pixels
80x25 characters of 8x8 pixels
2 attributes picked from 16 colours; 1 bit per pixel
1 page ega
2 pages pcjr
tandy
SCREEN 3
Low-res 16-colour pcjr
tandy
-
160x200 pixels
20x25 characters of 8x8 pixels
16 attributes picked from 16 colours; 4 bits per pixel
2 pages
SCREEN 3
Hercules monochrome hercules
-
720x348 pixels
80x25 characters of 9x14 pixels (with bottom line truncated by 2 px)
2 attributes; 1 bit per pixel
2 pages
SCREEN 3—255
Altissima risoluzione olivetti
-
640x400 pixels
80x25 characters of 8x16 pixels
2 attributes of which one picked from 16 colours; 2 bits per pixel
1 page
SCREEN 4
Med-res 4-colour pcjr
tandy
-
320x200 pixels
40x25 characters of 8x8 pixels
4 attributes picked from 16 colours; 2 bits per pixel
2 pages
SCREEN 5
Med-res 16-colour pcjr
tandy
-
320x200 pixels
40x25 characters of 8x8 pixels
16 attributes picked from 16 colours; 4 bits per pixel
1 page
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
-
640x200 pixels
80x25 characters of 8x8 pixels
4 attributes picked from 16 colours; 2 bits per pixel
1 page
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
-
320x200 pixels
40x25 characters of 8x8 pixels
16 attributes picked from 16 colours; 4 bits per pixel
8 pages
SCREEN 8
EGA colour ega
-
640x200 pixels
80x25 characters of 8x8 pixels
16 attributes picked from 16 colours; 4 bits per pixel
4 pages
SCREEN 9
EGA colour ega
-
640x350 pixels
80x25 characters of 8x14 pixels
16 attributes picked from 64 colours; 4 bits per pixel
2 pages
SCREEN 10
EGA monochrome ega
monitor=mono
-
640x350 pixels
80x25 characters of 8x14 pixels
4 attributes picked from 9 pseudocolours; 2 bits per pixel
2 pages
NTSC Composite Colorburst
On CGA, Tandy and PCjr, colorburst
has the following effects, depending on the
type of monitor - RGB (default) or composite:
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.
Erase
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:
Notes
-
At least one parameter must be specified.
-
Composite colour artifacts are emulated only crudely in PC-BASIC, and not at
all in
SCREEN 1
.
Errors
-
No parameters are specified: Missing operand.
-
Any parameter has a string value: Type mismatch.
-
Any parameter is not in
[-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 an operating system subshell on the console.
If command
is specified, the command is executed on the shell and execution
returns to the program.
To enable this statement, the shell
option must be set to
a valid command interpreter.
Parameters
-
command
is a string expression.
Notes
-
Be careful when enabling this command, as it allows the running BASIC program full access to your files and operating system.
Errors
-
shell
option is not specified: Illegal function call.
-
command
has a number value: Type mismatch.
-
All output from the operating system subshell, including error messages, is displayed
on the PC-BASIC screen.
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.
Parameters
-
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 [-1—15]
. 0 is silent, 15 is full
volume; every step less reduces the volume by 2 dB. -1 is also full volume.
(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}
)
Notes
-
On PCjr and Tandy, Frequencies below 110 Hz are played as 110 Hz.
-
If
duration
is zero, any active background sound is stopped and
the sound queue is emptied.
-
If
duration
is zero, volume
and voice
must not be specified.
-
If
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
.
-
If
frequency
equals 32767
or 0
, a silence of length duration
is queued.
Errors
-
Any argument has a string value: Type mismatch.
-
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}
Switches the external speaker on or off and toggles the availability of advanced sound capabilities on PCjr and Tandy. This includes 3-voice
sound, noise generation and volume control. Clears the background music queue.
Notes
-
Only available with
syntax={pcjr | tandy}
.
-
On PC-BASIC, both the
internal and the external speaker are emulated through the same sound
system.
Errors
-
This statement is used and
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.
Parameters
-
button
is a numeric expression in [0, 2, 4, 6]
.
Errors
-
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
.
Notes
-
The variables are exchanged by reference. If, for example,
var_0
is a FIELD
variable and var_1
is not, then
SWAP
will reverse those roles.
Parameters
-
var_0
and var_1
are variables or array elements of
the same type. var_1
must have been previously defined.
Errors
-
var_1
is undefined: Illegal function call.
Note that no error is raised if var_0
is undefined, and that after this error both variables will be defined.
-
The types of
var_0
and var_1
are not the same: Type mismatch.
SYSTEM
SYSTEM
Exits the interpreter.
Notes
-
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 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}
.
Errors
-
If
term
is not set,
this statement raises Internal error
.
-
If
syntax
is not set to
pcjr
or tandy
, this keyword is not present.
Calling TERM
will raise Syntax error.
TIME$
(statement)
TIME$ = time
Sets the current BASIC time to time
.
Parameters
-
Time is a string expression
of the form
"HH{:|.}mm{:|.}ss"
where
0 <= HH < 24
, 0 <= mm < 60
and 0 <= ss < 60
.
Each position may have one or two characters.
Notes
-
PC-BASIC stores an offset to the system time and uses this for future
calls to
TIME$
and
DATE$
functions in the same interpreter session.
The system time is not changed, unlike GW-BASIC under MS-DOS.
Errors
-
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.
Notes
-
Tracing is turned off by the
NEW
and
LOAD
statements.
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
.
Parameters
-
file_number
is a numeric expression in [0—255]
.
-
record_0
and record_1
are numeric expressions in [1—2^25-2]
.
Errors
-
Any parameter has a string value: Type mismatch.
-
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.
-
If
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.
Parameters
-
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.
Errors
-
Any of the parameters has a string value: Type mismatch.
-
Any of the coordinates is not in
[-32768—32767]
: Overflow.
-
Any of the coordinate pairs is outside the physical screen: Illegal function call.
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.
Parameters
-
top_row
and bottom_row
are
numeric expressions in [1—24]
.
Notes
-
If
syntax={pcjr | tandy}
and
KEY OFF
is set, bottom_row
may be 25.
Otherwise, screen row 25 cannot be part of the
scrolling area.
Errors
-
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
.
Notes
-
A limited number of machine ports are emulated in PC-BASIC.
See
INP
.
Errors
-
Any parameter has a string value: Type mismatch.
-
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.
Notes
-
WHILE—WEND
loops can be nested. WEND
jumps to the most recent WHILE
statement that has not been closed by another WEND
.
Errors
-
All previous
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.
Parameters
-
expr
is a numeric expression.
Errors
-
No matching
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.
Notes
-
When changing screen width in graphics mode, the video mode is changed.
The following changes occur:
SCREEN 1
(40) ↔ SCREEN 2
(80)
SCREEN 7
(40) ↔ SCREEN 8
(80)
SCREEN 7
(40) ← SCREEN 9
(80)
-
Screen width value 20 is only allowed on Tandy and PCjr. Changing to this width
changes to
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)
Parameters
-
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.
Errors
-
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.
Parameters
-
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.
Errors
-
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.
Parameters
-
x0
, y0
, x1
, y1
are numeric expressions.
Errors
-
Any of the coordinates have a string value: Type mismatch.
-
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.
Parameters
-
expr_0, expr_1, ...
are expressions whose value is to be printed.
Errors
-
file_num
has a string value: Type mismatch.
-
file_num
is open for INPUT
: Bad file mode.