Language reference

Metasyntax
Definitions
Literals
- String literals
- Numeric literals
Variables
- Types
- Arrays
Operators
Functions
- ABS, ACOS, ASC, ASIN, ATAN, CHR$, COS, DEEK, EXP, FIX, FN, INKEY$, INP, INSTR, INT, LEFT$, LEN, LOG, MID$, PEEK, RIGHT$, RND, SGN, SIN, SQR, STR$, STRING$, TAN, USR, VAL, VAL$
Statements
- BEEP, BLOAD, BSAVE, CALL, CHDIR, CIRCLE, CLEAR, CLOSE, CLS, COLOR, CONT, COPY, DATA, DEF FN, DELETE, DIM, DOKE, DRAW, EDIT, ELSE, END, ERROR, FILES, FOR, GOSUB, GOTO, IF, INPUT, KEY, KILL, LET, LINE, LIST, LOAD, LOCATE, MERGE, MKDIR, NAME, NEW, NEXT, OLD, ON, ON ERROR, OPEN, OUT, PALETTE, PLAY, PLOT, POKE, PRINT, RANDOMIZE, READ, REM, RENUM, RMDIR, RUN, SAVE, SCREEN, SEEK, SOUND, STOP, TRACE, WAIT, WEND, WHILE
Errors and messages
- Errors
- Other messages

This documentation describes the SE Basic IV language. Differences with Microsoft BASIC do arise, and where this is the case they are documented.

Note that Microsoft's official documentation 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 behavior. The errors in this document are therefore all our own. Contact us if you encounter them.

Metasyntax

In descriptions of BASIC syntax, the following conventions apply. Exact rendering of the markup may vary depending on the means used to display this documentation.

bold: Type exactly as shown.

italic: Replace with appropriate metavariable.

[a]: Entities within square brackets are optional.

{ a | b }: Disjunct alternatives of which one must be chosen.

[ a | b ]: Optional disjunct alternatives.

a ...: Preceding entity can be repeated.

Definitions

A program line consists of a line number followed by a compound statement. Program lines are terminated by a CR or by the end of the file.

A line number is a whole number in the range [1 to 16383]. Note that Microsoft BASIC supports line numbers in the range [0 to 65529].

A compound statement consists of statements separated by colons:

statement [: statement] ...

An expression takes one of the following forms:

unary_operator{literal|variable|array_element|function}

expression binary_operator expression

(expression)

whose elements are described the sections Literals, Variables, Operators and Functions.

An array element takes the form:

array{[|(}numeric_expression[,numeric_expression] ... {)|]}

Literals

String literals

String literals are of the following form:

"[characters]"

where characters is a string of characters. Any character from the current code page can be used.

String literals should not contain any of the characters in the ASCII range $00—$1F, which lead to unpredictable results. There is no escaping mechanism. To include one of the above characters in a string, use [string concatenation](#string concatenation) and the CHR$ function.

Numeric literals

Numeric literals have one of the following forms:

[+|-] [0|1|2|3|4|5|6|7|8|9]... [.][0|1|2|3|4|5|6|7|8|9]... [{E|e|}

$[0|1|2|3|4|5|6|7|8|9|A|B|C|D|E|F|a|b|c|d|e|f]...

@[0|1|2|3|4|5|6|7]...

%[0|1]...

Literals may contain spaces.

Hexadecimal, octal and binary literals denote positive integers and do not include a sign. They must range between [$0 to $ffff]. This is in contrast to Microsoft BASIC where the range [$8000 to $ffff] is interpreted as a two's complement negative integer; for example, $FFFF = -1.

Floating-point literals must be specified in decimal notation. The decimal separator is the point. A base-10 exponent may be specified after E.

Examples of valid numeric literals are -1 42 1.3523523 .235435 -.3 3. 1.1e+7 1e2 1e-2 @7 $ffff @20 $ @ % 65537 1.1

Note that expressions such as @-77 are legal; these are however not negative octals but rather the expression @ (empty octal; zero) less 77 (decimal 77).

Variables

Variable names must start with a letter; all characters of the variable name (except the $) must be letters A to Z or figures 0 to 9. A dot (.) is not permitted. All characters in the name are significant. A variable name must not be identical to a reserved word or a reserved word plus '$'. Therefore, for example, you cannot name a variable TO$ but you can name it AS$. Variable names may contain any reserved word. Variable names may also start with a reserved word. Thus COST and LUSR$ are legal variable names.

For each name, two different variables may exist corresponding to the two types. That is, you can have A$ and A as different variables.

Currently, the array A() is separate from the scalar variables of the same name but the array A$() is not. Unlike Microsoft BASIC, the latter is a character array.

Types

SE Basic IV recognizes three variable types. Strings are indicated with a $ suffix. Whole numbers in the range -65536 to 65535 are stored as integers. All other numbers are stored as extended-precision floating-point numbers precise to ~9 significant figures.

Arrays

Arrays are indexed with round brackes. Multidimensional arrays are specified by separating the indeces with commas: A(0, 0), A(0, 0, 0), and so on.

By default, arrays are indexed from 1. In Microsoft BASIC arrays are indexed from 0, but this can be changed using OPTION BASE 1.

Arrays can be allocated by specifying the largets allowed index using DIM. Unlike Microsoft BASIC, if all indeces of the array are 10 or less, they must be explicitly allocated. Also, it is not necessary to perform any actions beofre re-allocating an array.

Multi-dimensional arrays are stored in column-major order, such that A(2, 0) immediately follows A(1,0).

Operators

Order of precedence

The order of precedence of operators is as follows, from tightly bound (high precedence) to loosely bound (low precedence):

10. ^
9. * /
8. \
7. MOD
6. + - (unary and binary)
5. = <> < > <= >=
4. NOT (unary)
3. AND
2. OR
1. XOR

Unlike Microsoft BASIC, EQV and IMP are not currently supported. SE Basic IV converts the alternates for not equal (><), greater than or equal (=<) or less than or equal (=>) to standard notation.

Expressions within parentheses () are evaluated first. All binary operators are left-associative: operators of equal precedence are evaluated left to right.

Examples

Exponentiation is more tightly bound than negation: -1^2 = -(1^2) = -1 but (-1)^2 = 1.
Exponentiation is left-associative: 2^3^4 = (2^3)^4 = 4096.

Errors

If any operator other than +, - or NOT is used without a left operand, an error is raised.
At the end of a statement, if any operator is used without a right operand, an error is raised. If this occurs elsewhere inside a statement, such as within brackets, an error is raised.

Mathematical operators

Mathematical operators operate on numeric expressions only. Note however that + can take the role of the string concatenation operator if both operands are strings.

Code	Operation	Result
`x ^ y`	Exponentiation	`x` raised to the power of `y`
`x * y`	Multiplication	Product of `x` and `y`
`x / y`	Division	Quotient of `x` and `y`
`x \ y`	Truncated division	Integer quotient of `x` and `y`
`x MOD y`	Modulo	Integer remainder of `x` by `y` (with the sign of `x`)
`x + y`	Addition	Sum of `x` and `y`
`x - y`	Subtraction	Difference of `x` and `y`
`+ y`	Unary Plus	Value of `y`
`- y`	Negation	Negative value of `y`

Notes

The expression 0^0 will return 1 and not raise an error, even though, mathematically, raising zero to the zeroeth power is undefined.

Errors

If either operand is a string, an error will be raised. The exception is + which will only raise Type mismatch if either but not both operands are strings.
If y=0, x / y, x MOD y and x \ y will raise an error.
If x=0 and y<0, x^y will raise an error.
If the result of any operation is too large to fit in a floating-point data type, an error is raised.
If operands or result of \ or MOD are not in [-32768 to 32767], an error is raised.

String operators

Code	Operation	Result
`x$ + y$`	Concatenation	The contents of `x$` followed by the contents of `y$`
`x$ * y`	Repetition	The contents of `x$` is repeated `y` times. If `y` is negative, the result is mirrored.
`x$ AND y`	Selection	If `y` is zero, the result is an empty string, otherwise `x$`

Relational operators

Relational operators can operate on numeric as well as string operands; however, if one operand is string and the other numeric, an error is raised.

Relational operators return either 0 (for false) or -1 for true.

Code	Operation	Result
`=`	Equal	True if `a` equals `b`, false otherwise.
`<>` (`><`)	Not equal	False if `a` equals `b`, true otherwise.
`<`	Less than	True if `a` is less than `b`, false otherwise.
`>`	Greater than	True if `a` is greater than `b`, false otherwise.
`<=` (`=<`)	Less than or equal	False if `a` is greater than `b`, true otherwise.
`>=` (`=>`)	Greater than or equal	False if `a` is less than `b`, true otherwise.

When operating on numeric operands, both operands are compared as floating-point numbers according to the usual ordering of numbers. The equals operator tests for equality to within machine precision for the highest-precision of the two operator types.

When comparing strings, the ordering is as follows.

Two strings are equal only if they are of the same length and every character code of the first string agrees with the corresponding character code of the second. This includes any whitespace or unprintable characters.
Each character position of the strings is compared starting with the leftmost character. When a pair of different characters is encountered, the string with the character of lesser code point is less than the string with the character of greater code point.
If the strings are of different length, but equal up to the length of the shorter string, then the shorter string is less than the longer string.

Note: the tokenizer converts the symbols ><, => and =< to <>, >= and <= respectively.

Bitwise operators

SE Basic IV has no Boolean type and does not implement Boolean operators. It does, however, implement bitwise operators. In direct mode, SE Basic IV enables characters to be used as a subsitute for typing the operator name.

Character	Code
`~`	`NOT`
`&`	`AND`
`\|`	`OR`

Bitwise operators operate on numeric expressions only. Floating-point operands are rounded to integers before being used.

Code	Operation	Result
`NOT y`	Complement	`-y-1`
`x AND y`	Bitwise conjunction	The bitwise `AND` of `x` and `y`
`x OR y`	Bitwise disjunction	The bitwise `OR` of `x` and `y`
`x XOR y`	Bitwise exclusive or	The bitwise `XOR` of `x` and `y`

These operators can be used as Boolean operators only if -1 is used to represent true while 0 represents false. Note that SE Basic IV represents negative integers using the two's complement, so NOT 0 = -1. The Boolean interpretation of bitwise operators is given in the table below.

Be aware that when used on integers other than 0 and -1, bitwise operators can not be interpreted as Boolean operators. For example, 2 AND 1 returns 0.

Errors

If either (but not both) operands to a concatenation are numeric, an error will be raised.

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 Microsoft 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 Microsoft BASIC syntax for functions without inputs. For example, one can do DEF FN A=1: PRINT FN A in which no parentheses are allowed.

In Microsoft BASIC, the input of a function must be contained in parentheses. In SE Basic IV the parentheses are usually optional.

ABS

y = ABS(x)

address is a numeric expression in [-32768 to 65535]. Negative values are interpreted as their two's complement.

EXP

y = EXP(x)

Returns the exponential of x, that is e to the power x.

Parameters

x is a number- valued expression.

Errors

x has a string value: Type mismatch.
x is larger than the natural logarithm of the maximum single-precision value: Overflow.

FIX

whole = FIX(number)

Returns a 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 required.

Parameters

name is the name of a previously defined function.
arg_0, arg_1, ... are expressions, given as parameters to the function.

Notes

In Microsoft BASIC, spaces between FN and name are optional.
Unlike Microsoft BASIC, in SE Basic IV, functions can be called recursively, albeit without tail call optimization.

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.

INKEY$

key = INKEY$ [ #file_num]

Returns one character from the stream file_num. If no stream is specified, 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-character string holding the e-ASCII code of the pressed key.

Notes

When a function key F1 to F15 is pressed, INKEY$ will return the letters of the associated macro unless it's 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 a machine port.

Parameters

port is a numeric expression in [0 to 65535].

INSTR

position = INSTR([start,] parent, chlid)

Returns the location of the first occurrence of the substring chlid in parent.

Parameters

parent and child are string expressions.
start is a numeric expression in [1 to 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.
If the start index is 0 (instead of 1), it still searches from the beginning.
If child is empty, it is found right away at the start index.

Errors

start has a string value or parent or child have numeric values: Type mismatch.
start is not in [-32768 to 32767]: Overflow.
start is not in [1 to 255]: Illegal function call.

INT

whole = INT(number)

Returns number truncated towards negative infinity.

Parameters

number is a numeric expression.

Notes

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 to 65535]. Negative values are interpreted as their two's complement.

Notes

Currently PEEK only accepts values in the range [0 to 65535] and ignores SEG, returning values from the 64K address space.

Errors

address has a string value: Type mismatch.
address is not in [-32768 to 65535]: Overflow.

RIGHT$

child = RIGHT$(parent, num_chars) ...

RND

random = RND[(x)]

Returns a pseudorandom number in the interval `0 to 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

SE Basic IV's RND function produces different random numbers from Microsoft BASIC.
It is a very poor random number generator. RND should not be used for cryptography, scientific simulations or anything else remotely serious.

Errors

x has a string value: Type mismatch.

STRING$

string = STRING$(length, char)

Returns a string of length times the character char.

Parameters

If char is a numeric expression, it must be in [0 to 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 to 32767]: Overflow.
char or length is not in [0 to 255]: Illegal function call.

VAL$

repr = VAL$(string)

Evaluates a string as a string expression. For example

10 INPUT a$, x$
20 PRINT VAL$ a$

The string value assigned to a$ should be an expression using x$. For example, "x$+x$". A string value is then assigned to x$, for example "yo". VAL$ strips the quotes of the value of a$ to get x$+x$ and evaluates it using the value assigned to x$ displaying the result yoyo.

Notes

This function is not present in Microsoft BASIC. It is very useful for creating recursive functions, if used together with AND applied to string arguments, allowing for selective evaluation.
Expressions between curly braces { and } are not evaluated, but their syntax is checked upon entering. They are interpreted as strings that can be passed to VAL$ for actual evaluation.

Statements

BEEP

BEEP

Beep the speaker at approximately 800Hz for 0.25s.

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 to 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 to 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 to 65535] indicating the offset into the current [DEF SEG](#DEF-SEG"> segment from where to start reading.
length is a numeric expression in the range [-32768 to 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 to 65535]: Overflow.
length is not in the range [-32768 to 65535]: Overflow.

CALL

CALL address_var [, p0, p1, ...]

Executes a machine language subroutine.

Parameters

address_var is a numeric variable.
p0, p1, ... are variables.

Errors

address_var is a string variable: Type mismatch.
address_var is a literal: Syntax error.

CHDIR

CHDIR dir_spec

Change the current folder on a disk device to dir_spec. Each disk device has its own current folder.

Parameters

The string expression dir_spec is a valid file specification indicating an existing folder 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 x , y , r

Draws a circle where x and y are the center coordinates and r is the radius.

CLEAR

CLEAR [mem_limit]

Clears all variables, arrays, DEF FN user functions. Closes all files. Turns off all sound. Clears all ON ERROR traps. Clears the loop stack.

Parameters

mem_limit specifies the upper limit of usable memory. Default is previous memory size. Default memory size is 65535.

Notes

If called inside a FOR to NEXT or WHILE to 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 is not in [0 to 65535]: Overflow.
mem_limit is too low: Address out of range.

CLOSE

CLOSE [[#] file_0 [, [#] file_1] ...]

Closes streams. If no file numbers are specified, all open streams [3 to 15] are closed. The hash (#) is optional and has no effect.

Parameters

file_1, file_2, ... are numeric expressions yielding stream numbers.

Errors

file_1, file_2, ... are not in [0 to 15]: Bad I/O device.
file_1, file_2, ... are not open streams: Undefined stream.
file_1, file_2, ... have a string value: Type mismatch.
The statement ends in a comma, Syntax error.
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 that determines what is cleared:

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.

Errors

x is has a string value: Type mismatch.
x is not in [-32768 to 32767]: Overflow .
x is not in [0, 1, 2]: Illegal function call.
If an error occurs, the screen is not cleared.

COLOR

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 to 15]. This specifies the new foreground attribute.
background is a numeric expression in 0 to 15. This specifies the new background attribute.
border is a numeric expression in [0 to 15] specifying the border attribute. It is taken MOD 8: Values 8 to 15 produce the same colour as 0 to 7.

Errors

Any of the parameters has a string value: Type mismatch.
Any of the parameters is not in [-32768 to 32767]: Overflow.
foreground is not in [0 to 31], background is not in [0 to 15] or border is not in [0 to 15]: Illegal function call.
Statement is used in SCREEN 2: Illegal function call.

COPY

COPY file_spec_1 TO file_spec_2

Copies the disk file file_spec_1 to file_spec_2.

Parameters

The string expressions file_spec_1 and file_spec_2 are valid file specifications indicating the source and destination files. The first must point to an existing file on a disk device.

Notes

Typically, this command is not present in Microsoft BASIC.

Errors

file_spec_1 or file_spec_2 have number values: Type mismatch
file_spec_1 does not exist: File not found

CONT

CONT

Resumes execution of a program that has been halted by STOP, END or Esc.

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 (for example, GOSUB 100:PRINT A$), CONT will overwrite the running direct line. As the subroutine RETURNs to the position after the GOSUB in the old direct line, strange things may happen if commands are given after CONT. In Microsoft 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 SE Basic IV, 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.

Errors

If the type of the literal does not match that of the corresponding READ statement, a Syntax error occurs on the DATA statement.

DEF FN

DEF FN[ ]name [( arg_0 [, arg_1] ...)] = expression

Defines a function called FN name (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.

Example

Create the recursive function FN F(n) to calculate the factorial for n:

DEF FN F(N)=VAL (({N*FN F(N-1)} AND N)+({1} AND (N=0)))

Notes

This statement may only be used on a program line.
As the function must be a single expression and SE Basic IV does not have a ternary operator, the only way to define a recursive function that actually terminates is by using VAL or VAL$.
Do not use the function that you defining within its own definition. This will corrupt BASIC when the function is called. For example: DEF FN A()=FN A():PRINT FN A().

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 SE Basic IV 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.

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.

Parameters

line_number_0 and line_number_1 are line numbers in the range [0 to 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 arrays. The DIM statement also fixes the number of indices of the array. An array can only be allocated once; to re-allocate an array, ERASE or CLEAR must be executed first. If an array is first used without a DIM statement, it is automatically allocated with its maximum indices set at 10 for each index position used. If an array's DIM statement specifies no indices, it is allocated with a single index with maximum 10. The least index allowed is determined by OPTION BASE.

Parameters

name is a legal variable name specifying the array to be allocated.
limit_0, limit_1, ... are numeric expressions that specify the greatest index allowed at that position.

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 to 32767]: Overflow.
limit_0, limit_1, ... are negative: Illegal function call.
The array exceeds the size of available variable space: Out of memory.

DOKE

DOKE address, value

Sets the 16-bit value of the memory byte pair at segment * 16 + address to value, where segment is the current segment set with DEF SEG.

Parameters

address is a numeric expression in [0 to 65535]. Negative values are interpreted as their two's complement.
value is a numeric expression in [0 to 65535].

Notes

DEF SEG is not yet implemented in SE Basic IV.

Errors

address or value has a string value: Type mismatch.
address is not in [-32768 to 65535]: Overflow.
value is not in [-32768 to 32767]: Overflow.
value is not in [0 to 65535]: Illegal function call.

DRAW

DRAW x , y

Draws a line x pixels to the right and y pixels up from the last PLOT location. Accepts negative values.

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.

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 to 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. Unlike Microsoft BASIC, a colon : preceding the ELSE statement is required. However, if you enter a space before ELSE the tokenizer will add the colon for you. 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.

ERROR

ERROR error_number

Raises the error with number error_number.

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 to 32767]: Overflow.
error_number is not in 1 to 255]: Illegal function call.

FILES

FILES [filter_spec]

Displays the files fitting the specified filter in the specified folder on a disk device. If filter_spec is not specified, displays all files in the current working folder.

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

Wildcards are not currently supported.

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 to NEXT loop.

Initially, loop_var is set to start. Then, the statements between the FOR statement and the [](#NEXT">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.

Parameters

loop_var is a numeric 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 an array element: Syntax error .
loop_var is an integer variable and a start, stop or step is outside the range [-32768, 32767]: Overflow .

GOSUB

GO[ ]SUB line_number [anything]

Jumps to a subroutine at line_number. The next [](#RETURN">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 (for example, 6553)

GOTO

GOTO 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

No spaces are allowed between GO and TO.

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 to THEN to 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

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">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.

KEY (macro definition)

KEY key_id, string_value

Defines the string macro for functino key key_id. Only the first 15 characters of string_value are stored.

Parameters

key_id is a numeric expression in the range [1 to 15].
string value is a string expression.

Notes

If key_id is not in the prescribed range, an error is raised.
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 to 32767]: Overflow.
key_id is not in [1 to 255]: Illegal function call.
key_id has a string value: Type mismatch.

KEY (macro list)

KEY LIST

Prints a list of the 15 function keys with the functino-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 represenation, which is a symbolic representation of the effect as control characters on the screen.

Code point	Replacement	Usual glyph
`$07`	`$0E`	♫
`$08`	`$FE`	■
`$09`	`$1A`	→
`$0A`	`$1B`	←
`$0B`	`$7F`	⌂
`$0C`	`$16`	▬
`$0D`	`$1B`	←
`$1C`	`$10`	►
`$1D`	`$11`	◄
`$1E`	`$18`	↑
`$1F`	`$19`	↓

KEY (macro toggle)

KEY {ON|OFF}

Toggles function-key macros ON or OFF.

KILL

KILL file_spec

Deletes a file on a disk device.

Parameters

The string expression file_spec is a valid file specification indicating the file to delete. It must point to an existing file on a disk device.

Errors

file_spec has a number value: Type mismatch.
The file file_spec is open: File already open
The file or path file_spec does not exist: 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.

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.

LIST

LIST [# file_num;] [line_number_0][, ][line_number_1]

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. 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 Microsoft BASIC, LIST will not show line numbers 65531 to 65535 inclusive.
SE Basic IV's line range is currently [0 to 16383].
There is no LLIST command. Instead, LIST can be directed to the printer stream using LIST #.

Parameters

line_number_0 and line_number_1 are line numbers in the range [0 to 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_num is a valid stream indicating the file to list to.

Errors

A line number is greater than 65529: Syntax error.
file_num has a string value: Type mismatch.

LOAD

LOAD file_spec [,{"R"|"T"}]

Loads the program stored in a file into memory. Existing variables will be cleared and any program in memory will be erased. LOAD implies a [CLEAR](#CLEAR).

If ,"R" is specified, keeps all data files open and runs the specified file. If ,"T" is specified, loads a tokenized program.

Parameters

The string expression file_spec is a valid file specification indicating the file to read the program from.

Notes

Unlike Microsoft BASIC, SE Basic IV always expects BASIC programs to be in plain text format.
Unlike Microsoft BASIC, the R directive must be in quotes. Otherwise SE Basic IV would treat it as a variable.

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]

Set the next print position to row, col on the screen.

Notes

In Microsoft BASIC, the cursor can be displayed or made invisible and its shape can be changed. This is not supported in SE Basic IV.

Errors

Any parameter has a string value: Type mismatch.
Any parameter is not in [-32768 to 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 to 255] on Tandy/PCjr): Illegal function call.

MERGE

MERGE file_spec

Merges the program stored in a file into memory.

Parameters

The string expression file_spec is a valid file specification indicating the file to read the program from.

Notes

Unlike Microsoft BASIC, SE Basic IV always expects BASIC programs to be in plain text format.

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.

MKDIR

MKDIR dir_spec

Creates a new folder on a disk device.

Parameters

The string expression dir_spec is a valid file specification that specifies the path of the new folder on a disk device.

Errors

dir_spec is not a string: Type mismatch.
The parent folder does not exist: Path not found.
The folder name already exists on that path: Path/File access error.
The user has no write permission: Permission denied.

NAME

NAME old_name TO 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

new_name will be modified into all-uppercase 8.3 format.

Errors

old_name or new_name have number values: Type mismatch.
old_name does not exist: File not found.
old_name is open: File already open.
new_name exists: File already exists.

NEW

NEW

Stops execution of a program, deletes the program in memory, executes CLEAR and RESTORE and returns control to the user.

Iterates a FOR to NEXT loop: increments the loop variable and jumps to the [](#FOR">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.

OLD

OLD

Loads a backup from disk of the program that was in memory the last time a NEW command was issued and returns control to the user.

ON

ON n {GOTO|GOSUB} line_number_0 [, line_number_1] ...

Jumps to the nth 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 to 255].
line_number_0, <var>line_number_1, ... are existing line numbers in the program.

Errors

n has a string value: Type mismatch.
n is not in [-32768 to 32767], Overflow.
n is not in [0 to 255]: Illegal function call.
The line number jumped to does not exist: Undefined line number.

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">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 # file_num, "mode_char" [,file_spec]

Opens a data file on a device.

Parameters

The string expression file_spec is a valid file specification.
file_num is a valid stream [3 to 15].
mode_char is a string expression of which the first character is one of:
- ["K", "S"] - system channel (keyboard or screen).
- `["I", "O", "A", "R"] - access mode for a disk file.
- other alpha character - a used defined channel.

Access modes

The mode_char are as follows:

`mode_char`	Meaning	Effect
"I"	INPUT	Opens a text file for reading and positions the file pointer at the start.
"O"	OUTPUT	Truncates a text file at the start and opens it for writing. Any data previously present in the file will be deleted.
"A"	APPEND	Opens a text file for writing at the end of any existing data.
"R"	RANDOM	Opens a file for random access.

A single character can be read with c$=INKEY$ #file_num or written with PRINT #file_num;c$;. Strings are terminated with a carriage return. A string can be read with INPUT #file_num;s$ or written with PRINT #file_num;s$.

File specification

file_spec is a non-empty string expression of the form "parameters".

parameters must specify a valid file path of the form [/][dirname/] ... filename.

In SE Basic IV, file support is provided using the OS kernel. UnoDOS 3 follows MS-DOS file system conventions with the exception that folder names are separated with forward slashes (/). SE Basic IV adds syntactic sugar to the short filename format. File names consist of an 8-character name and 3-character extension. Folder names consist of an 11-character name. Permissible characters are the printable ASCII characters in the range [$20 to $7E] excluding the characters " * + . , / : ; < = > ? \ [ ] |. Spaces are allowed but are converted to underscores.

A path starting with a forward slash 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 folder on the specified device. The special folder name .. refers to the parent folder of a preceding path, or the parent folder of the current folder if no path is given. The special folder name . refers to the same folder as given by the preceding path, or the current folder if no preceding path is given.

The LOAD and SAVE statements do not currently implicitly add a default extension .BAS if no extension is specified..

Compatibility notes

UnoDOS 3 allows certain characters in the range $7F to $FF. However, their permissibility and interpretation depends on the console code page, which may be different from the display code page currently in use. Therefore you should avoid using these characters.

Errors

file_num is a non-existent stream: Undefined stream.
file_num is not in range [0 to 15]: Bad I/O device.
mode_char is a non-existent channel: Undefined channel.
file_spec is non-existent in input or append mode: File not found.

OUT

OUT port, value

Sends a byte to an emulated machine port.

Parameters

port is a numeric expression in [0 to 65535].
value is a numeric expression in [0 to 255].

Errors

port or value has a string value: Type mismatch.
port is not in [0 to 65535]: Overflow.
value is not in [0 to 32767]: Overflow.
value is not in [0 to 255]: Illegal function call.

PALETTE

PALETTE [attrib, color]

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 from [0 to 63].
color is a numeric expression between [0 and 255]

Notes

Colors are entered in compressed RGB format (lowest to highest bit). The red and green levels are each stored in three bits (0 to 7) while the blue level is stored in two bits (0 to 3). The easiest way to enter values is in octal (@BGR). For example, to set attribute to maximum blue, you would enter PALETTE attribute, @300.

Errors

attrib or colour has a string value: Type mismatch.
attrib or colour is not in [ to 32767]: Overflow
attrib or colour is not in range: Illegal function call

PLAY

PLAY [# device,] string[, string[, ...]

PLAY up to 8 strings of music data in MML format to the square wave generator or GM-MIDI.

Parameters

device is 0 (PSG) or 1 (MIDI).
string is a valid MML command sequence.

Errors

string is not valid MML: Syntax error

Music Macro Language

SE Basic IV implements a version of MML (Music Macro Language).

Other than note names (c,d,e,f,g,a,b), commands are case-insensitive.
Upper case notes (C,D,E,F,G,A,B) are one octave higher than the current octave.
The default octave is 4.
R is a rest.
- before a note flattens it.
+ or # before a note sharpens it.
& indicates tied notes.
Comments can be enclosed between single quote marks ( ' ).
O sets the octave (1 to 8).
(optional) L sets the note length (0 to 9) as classic MML, or triplets (10 to 12).
Phrases in square brackets ( [``] ) are played twice.
Brackets can be nested up to four levels.
A closing bracket without a matching opening bracket loops the preceding phrase indefinitely.
T sets the tempo in BPM (32 to 255, default 120).
V sets the volume (0 to 15) and switches off envelopes on that channel.
S sets the envelope waveform (0 to 15) and activates it.
M sets the modulation frequency (1 to 65536).
H sets the MIDI channel (1 to 16).
Z sends a command (0 to 255) to the MIDI port.
X exits the PLAY command immediately.
> increases the octave by one.
< decreases the octave by one

PLOT

PLOT x , y

Draws a pixel at coordinates x and y.

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 to 65535]. Negative values are interpreted as their two's complement.
value is a numeric expression in [0 to 255].

Notes

DEF SEG is not yet implemented in SE Basic IV.

Errors

address or value has a string value: Type mismatch.
address is not in [-32768 to 65535]: Overflow.
value is not in [-32768 to 32767]: Overflow.
value is not in [0 to 255]: Illegal function call.

PRINT

PRINT [# stream,] [expr_0|;|,|SPC( n)|TAB( n)] ... [USING format; uexpr_0 [{;|,} uexpr_1] ... [;|,]]

Writes expressions to the screen, a file or another device. If stream is specified, output goes to the file or device open under that number. ? is a shorthand for PRINT.

When writing a string expression to the screen, the following control characters have special meaning. Other characters are shown as their corresponding glyph in the current codepage.

Code point	Control character	Effect
`$07`	`BEL`	Beep the speaker.
`$08`	`BS`	Erase the character in the previous column and move the cursor back.
`$09`	`HT`	Jump to the next 8-cell tab stop.
`$0A`	`LF`	Go to the leftmost column in the next row; connect the rows to one logical line.
`$0B`	`VT`	Move the cursor to the top left of the screen.
`$0C`	`FF`	Clear the screen.
`$0D`	`CR`	Go to the leftmost column in the next row.
`$1C`	`FS`	Move the cursor one column to the right.
`$1D`	`GS`	Move the cursor one column to the left.
`$1E`	`RS`	Move the cursor one row up.
`$1F`	`US`	Move the cursor one row down.

Note: In SE Basic IV, anything after PRINT CHR$(12) is not printed.

Expressions can optionally be separated by one or more of the following keywords:

Keyword	Effect
`;`	Attaches two expressions tight together; strings will be printed without any space in between, numbers will have one space separating them, in addition to the space or minus sign that indicate the sign of the number.
`,`	The expression after will be positioned at the next available tab stop.
`'`	Inserts a newline.
`SPC(n)`	Produces `n` spaces, where `n` is a numeric expression. If `n` is less than zero, it defaults to zero. If `n` is greater than the file width, it is taken modulo the file width.
`TAB(n)`	Moves to column `n`, where `n` is a numeric expression. if `n` is less than zero, it defaults to zero. If `n` is greater than the file width, it is taken modulo the file width. If the current column is greater than `n`, `TAB` moves to column `n` on the next line.

If the print statement does not end in one of these four separation tokens, a newline is printed after the last expression. String expressions can be separated by one or more spaces, which has the same effect as separating by semicolons.

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 [](#boolean-operators">XORed 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">RND function.

Parameters

expr is a numeric expression.

Notes

For the same seed, SE Basic IV produces the same pseudorandom numbers as Microsoft BASIC 3.23.
The random number generator is very poor and should not be used for serious purposes. See [](#RND">RND for details.

Errors

expr has a string value: Illegal function call.
The user provides a seed outside [-32768 to 32767] at the prompt: Overflow.

READ

READ var_0 [, var_1] ...

Assigns data from a [](#DATA">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">RUN and [](#RESTORE">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.

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.

Notes

The following keywords can reference line numbers, which will be renumbered by RENUM: GOSUB, GOTO, LIST, RESTORE, RUN.

Errors

Any of the parameters is not in [0 to 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.

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.

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 folder on a disk device.

Parameters

The string expression dir_spec is a valid file specification that specifies the path and name of the folder.

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 .

RUN

RUN [line_number | app_name [, p0, p1, ...]]

Executes a program. Existing variables will be cleared and any program in memory will be erased. RUN implies a CLEAR. If an app_name is specified, opens the application.

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 app_name, if specified, is a valid application name (case-insensitive, truncated to the first 11 characters).
p0, p1, ... are variables.

Errors

line_number is not a line number in the current program: Undefined line number.
app_name cannot be found: File not found.

SAVE

SAVE file_spec [,"T"]

Stores the current program in a file.

If ,"T" is specified, saves a tokenized program.

Parameters

The string expression file_spec is a valid file specification indicating the file to store to.

Notes

In Microsofr BASIC you can append , A to save the file in plain text or , P to save a protected listing, otherwise the file is saved in tokenized format. In SE Basic IV the file is saved in plain text format unless you append , "T".

Errors

file_spec has a number value: Type mismatch.
file_spec is an empty string: Bad I/O device.
file_spec is too long: Bad I/O device.

SCREEN

SCREEN mode

Change the video mode. Video modes are described in the Video Modes section.

Parameters

mode is a numeric expression that sets the screen mode.

Video mode	Notes
`0`	Text mode. 80 x 24 characters. Two attributes picked from 16 colors.
`1`	Bitmap mode. 240 x 192 pixels. 40 x 24 characters of 6 x 8 pixels. 8 x 1 attributes from 16 colors.

Notes

The driver for SCREEN 1 is stored in RAM and can be replaced with a driver for any screen mode supported by the hardware.

Errors

No parameters are specified: Missing operand.
Any parameter has a string value: Type mismatch.
Any parameter is not in [-32768 to 32767]: Overflow.
mode is not an available video mode number for your video card setting: Illegal function call.

SEEK

SEEK # file_num, loc

Parameters

file_num is an open stream.
loc is a number between 0 and 2^32.

Errors

file_num is not open: Undefined stream.
file_num is not a valid stream (3 to 15): Undefined stream.

SOUND

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">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">PLAY function.

Parameters

frequency is a numeric expression in [37 to 32767] or 0 (for syntax={advanced | pcjr}) or in [-32768 to 32767] (for syntax=tandy).
duration is a numeric expression in [0 to 65535].
volume is a numeric expression in [0, 15]. 0 is silent, 15 is full volume; every step less reduces the volume by 2 dB. (For syntax={pcjr | tandy})
voice is a numeric expression in [0, 2], indicating which of the three tone voice channels is used for this sound. (For [](#--syntax">syntax={pcjr | tandy})

Notes

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">syntax={ pcjr | tandy } is not set and more than two arguments are specified: Syntax error.
frequency is not in [-32768 to 32767]: Overflow.
duration is not in [-65535 to 65535]: Illegal function call.
volume is not in [0 to 15]: Illegal function call.
voice is not in [0 to 2]: Illegal function call.

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.

TRACE

TRACE {ON|OFF}

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.

WAIT

WAIT frames

Pauses for (frames/60) seconds.

Parameters

frames is in [0 to 65535].

Notes

In Microsoft BASIC, WAIT waits for input from a given port.

Errors

Any parameter has a string value: 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.

Errors and messages

Errors

NEXT without FOR

A NEXT statement has been encountered for which no matching FOR can be found.
Syntax error

The BASIC syntax is incorrect. A statement or expression has been mistyped or called in one of many incorrect ways. This error is also raised on a DATA line if a READ statement encounters a data entry of an incorrect format.
RETURN without GOSUB

A RETURN statement has been encountered for which no GOSUB call has been made.
Out of DATA

A READ statement is attempting to read more data entries than can be found from the current DATA location onward.
Illegal function call

A statement, function or operator has been called with parameters outside the accepted range. This error is also raised for a large variety of other conditions – check the reference for the statement or function called.
Overflow

A numeric expression result or intermediate value is too large for the required number format.
Out of memory

There is not enough free BASIC memory to complete the operation. Too much memory is consumed by the program; variables, arrays and strings, or execution stacks for loops, subroutines or user-defined functions.
Undefined line number

A reference is made to a line number that does not exist in the program.
Subscript out of range

An array index (subscript) is used that is outside the range reserved for that array by the DIM statement.
Undefined variable

A simple variable has been used without assigning it a value, or a control variable has been used with NEXT without first setting it up in a FOR statement, or a subscripted value has been used before dimensioning the array with DIM.
Address out of range

The value specified in a CLEAR statement is either too big or too small.
Statement missing

A jump has been attempted to a statement that no longer exists.
Type mismatch

The expression used is of a type that cannot be converted to the required type for the function or statement. Most commonly, this is raised if a string argument is supplied to a statement or function that expects a number, or vice versa.
Out of screen

INPUT has generated more than 23 lines in the lower part of the screen.
Bad I/O device

File handling report.
Undefined stream

Attempted to read or write from a stream that has not been defined with an OPEN statement.
Undefined channel

Attempted to open a stream to an unrecognized channel.
Undefined user function

The FN function is called with a function name for which no definition was made by a DEF FN statement.
Line buffer overflow

There is not enough memory space left to enter the new program line.
FOR without NEXT

A FOR statement has been encountered for which no matching NEXT statement can be found.
WHILE without WEND

A WHILE statement has been encountered for which no matching WEND statement can be found.
WEND without WHILE

A WEND statement has been encountered for which no matching WHILE statement can be found.
File not found

A named file on a disk device cannot be found.
Input past end

An attempt is made to retrieve input from a file that has passed its end of file.
Path not found

An OPEN, MKDIR, RMDIR, or CHDIR statement is executed referring to a (parent) path that does not exist on the disk device.

Other messages

Break Program execution interrupted.

Ok Progam execution finished.

Uh oh!

Language reference

Metasyntax

Definitions

Literals

String literals

Numeric literals

Variables

Types

Arrays

Operators

Order of precedence

Examples

Errors

Mathematical operators

Notes

Errors

String operators

Relational operators

Bitwise operators

Errors

Functions

ABS

Parameters

ACOS

Parameters

Errors

ASC

Parameters

Errors

ASIN

Parameters

Errors

ATAN

Parameters

Errors

CHR$

Parameters

Errors

COS

Parameters

Errors

DEEK

Parameters

EXP

Parameters

Errors

FIX

Parameters

Notes

Errors

FN

Parameters

Notes

Errors

INKEY$

Notes

INP

Parameters

INSTR

Parameters

Notes

Errors

INT

Parameters

Notes

Errors

LEFT$

LEN

Parameters

Errors

LOG

Parameters

Errors

MID$

PEEK

Parameters

Notes

Errors

RIGHT$