Language guide

Working with programs
Control flow
Arrays and variables
Type conversion
String operations
Text and the screen
The printer
Keyboard input
Function-key macros
Calculations and maths
- Mathematical functions
- Random numbers
Devices and files
- File operations
- Devices
Graphics
Sound
Joystick and mouse
Disks and DOS
Serial communications
Event handling
Error handling
User-defined functions
Date and time
Including data in a program
Memory and machine ports
Legacy feature support
Features not yet implemented
Unsupported features

This documentation describes the SE Basic IV language, which aims to support programs written for Microsoft BASIC with minimal changes.

The Language Guide covers the language topic by topic, thematically grouping language elements used for a related purpose. Refer to the Language reference for a formal description of the language elements and their syntax.

Working with programs

Statement	Description
AUTO	Enter automatic line numbering mode.
CHAIN	Load a new program and run it, preserving common variables.
DELETE	Delete lines from the program.
EDIT	Print a program line to the screen for editing.
LIST	Print program lines to the screen.
LIST #	Print program lines to another device.
LOAD	Read a new program from file.
MERGE	Overlay a program file onto the current program
NEW	Clear the current program from memory.
OLD	Restore the previously cleared program to memory.
RENUM	Replace the program's line numbers.
RUN	Start the current program.
SAVE	Store the current program to file.
TRACE	Toggle line number tracing.

Control flow

A program is normally executed starting with its lowest line number (or the line number called by RUN). Statements on a line are executed from left to right. When all statements on a line are finished, execution moves to the next lowest line number, and so on until no line numbers are left. Control flow statements can be used to modify this normal flow of executon.

The END and STOP statements serve in a program to stop its execution and return to direct mode. When STOP is used, a Break message is printed. From direct mode, CONT can be executed to resume the program where it was stopped. While END seems intended to terminate the program, it does not preclude the user from resuming it with CONT.

Unconditional jumps can be made with GOTO. The program flow will continue at the line number indicated in the GOTO statement. Due to the SE Basic IV language's lack of sophisticated looping, branching and breaking constructs, unconditional jumps are essential and used frequently.

The GOSUB statement jumps to a subroutine. Similar to GOTO, this is an unconditional jump; however, the location of the call is stored and the program will continue its flow there after the subroutine terminates with a RETURN statement. Subroutines are somewhat like procedures in that they allow chunks of code that perform a given task to be separated from the main body of the program, but they do not have separate scope since all variables in SE Basic IV are global. They do not have return values. It is even possible to jump out of a subroutine to anywhere in the program by supplying the RETURN statement with a line number.

The ON statement provides an alternative branching construct. An integer value is used to selects one of a list of line numbers, and execution is continued from there. It can be used with a GOTO jump as wellas with a GOSUB subroutine call.

ON, GOTO and GOSUB can also be used from direct mode to start a program or subroutine without resetting variables.

The IF–THEN–ELSE construct tests for a condition and execute different code branches based on its truth value. This is not a block construct; all code in the THEN and ELSE branches must fit on one line. For this reason, branching is often used in combination with GOTO jumps. For example:

10 INPUT "How old are you"; AGE
20 IF AGE > 30 THEN 100
30 IF AGE < 30 THEN 200 ELSE PRINT "You are 30 years old."
40 END
100 PRINT "You are over 30."
110 END
200 PRINT "You are not yet 30."
210 END

The WHILE–WEND looping construct repeats the block of code between WHILE and WEND as long as a given condition remains true.

The FOR–NEXT construct repeats a block of code while a counter remains in a given range. The counter is set to a starting value at the first pass of the FOR statement and incremented by the STEP value at each pass of NEXT. For example:

10 FOR I=1 TO 10
20 PRINT STRING$(I, "*"); USING " [##]"; I
30 NEXT I

Looping constructs may be nested.

Control flow is also affected by event and error trapping.

Statement	Description
CONT	Continue interrupted program.
ELSE	Ignore the remainder of the line (standalone `ELSE`).
END	Stop execution of the program.
FOR	Start a for-loop.
GOSUB	Call a subroutine.
GOTO	Jump to another location in the program.
IF	Branch on a condition.
NEXT	Iterate a for-loop.
ON	Calculated jump or subroutine call.
RETURN	Return from subroutine.
STOP	Interrupt program execution.
WEND	Iterate a while-loop.
WHILE	Enter a while-loop.

Arrays and variables

Statement	Description
DIM	Allocate an array.
ERASE	Deallocate an array.
LET	Assign a value to a variable.
OPTION BASE	Set the starting index of arrays.
SWAP	Swap two variables.

Type conversion

Function	Description
ASC	Character to ordinal value.
CHR$	Ordinal value to character.
STR$	Numeric value to string representation. Defaults to decimal but can support base 2 (BIN$), 8 (OCT$), 16 (HEX$)
VAL	String representation to numeric value.
VAL$	String representation to string value.

String operations

Statement	Description
LSET	Copy a left-justified value into a string buffer.
MID$	Copy a value into part of a string buffer.
RSET	Copy a right-justified value into a string buffer.

Function	Description
INSTR	Find.
LEFT$	Left substring.
LEN	String length.
MID$	Substring.
RIGHT$	Right substring.
SPACE$	Repeat spaces.
STRING$	Repeat characters.

Text and the screen

Statement	Description
CLS	Clear the screen.
COLOR	Set colour and palette values.
LOCATE	Set the position and shape of the text screen cursor.
PALETTE	Assign a colour to an attribute.
PALETTE USING	Assign an array of colours to attributes.
COPY	Copy a screen page.
PRINT	Print expressions to the screen.
VIEW PRINT	Set the text scrolling region.
WIDTH	Set the number of text columns on the screen.

Function	Description
CSRLIN	Current row of cursor.
POS	Current column of cursor.
SCREEN	Character or attribute at given location.

The printer

Statement	Description
PRINT	Print expressions to the printer.

Function	Description
POS	Current column of cursor.

Keyboard input

Statement	Description
INPUT	Retrieve user input on the console.
LINE INPUT	Retrieve a line of user input on the console.

Function	Description
INKEY$	Nonblocking read from keyboard.
INPUT$	Blocking read from keyboard.

Function-key macros

Statement	Description
KEY	Define a function-key macro.

Calculations and maths

Mathematical functions

Function	Description
ABS	Absolute value.
ATAN	Arctangent.
ACOS	Arccosine.
ASIN	Arcsine.
COS	Cosine.
EXP	Exponential.
FIX	Truncation.
INT	Floor.
LOG	Natural logarithm.
SIN	Sine.
SGN	Sign.
SQR	Square root.
TAN	Tangent.

Random numbers

Statement	Description
RANDOMIZE	Seed the random number generator.

Function	Description
RND	Pseudorandom number.

Devices and files

File operations

Statement	Description
CLOSE	Close a file.
FIELD	Assign a string to a random-access record buffer.
GET	Read a record from a random-access file.
INPUT	Read a variable from a file.
LINE INPUT	Read a line from a file.
LOCK	Locks a file or a range of records against other use.
OPEN	Open a data file.
PUT	Write the random-access record buffer to disk.
RESET	Close all files.
UNLOCK	Unlocks a file or a range of records against other use.
WIDTH	Set the number of text columns in a file.
WRITE	Write expressions to a file.

Function	Description
EOF	End of file.
LOC	Location in file.
LOF	Length of file.
INPUT$	Read a string from a file.

Devices

SE Basic IV handles devices differently than Microsoft BASIC. A device is connected to a specific channel and one or more I/O streams can be connected to that channel. For example, the display is connected to channel S and by default stream #2 is connected to that channel S.

Device	Channel	Default stream
Keyboard	K	#1
Screen	S	#2

Graphics

Statement	Description
CIRCLE	Draw an ellipse or arc section.
DRAW	Draw a shape defined by a Graphics Macro Language string.
GET	Store a screen area as a sprite.
LINE	Draw a line segment.
PAINT	Flood-fill a connected region.
PSET	Put a pixel.
PRESET	Change a pixel to background attribute.
PUT	Draw a sprite to the screen.
SCREEN	Change the video mode.
VIEW	Set the graphics viewport.
WINDOW	Set logical coordinates.

Function	Description
POINT	Graphical pointer coordinates.
POINT	Pixel attribute.
PMAP	Convert between physical and logical coordinates.

Sound

Statement	Description
BEEP	Beep the speaker.
BEEP	Speaker switch.
NOISE	Generate noise.
PLAY	Play a tune encoded in Music Macro Language.
SOUND	Generate a tone.
SOUND	Sound switch.

Joystick and mouse

Statement	Description
STRIG	Joystick switch.

Function	Description
MOUSE	Status of mouse.
STICK	Status of joystick.
STRIG	Status of joystick fire button.

Disks and DOS

In SE Basic IV, the DOS is integrated into BASIC and there is no SHELL command.

Statement	Description
CHDIR	Change current directory.
COPY	Make a copy of a file.
FILES	List the files in the current directory.
KILL	Delete a file on a disk device.
MKDIR	Create a new directory.
NAME	Rename a file on disk.
RMDIR	Remove a directory.

Serial communications

Statement	Description
GET	Read bytes from a serial port.
PUT	Write bytes to a serial port.
TERM	Open the terminal emulator.

Event handling

Event trapping allows to define subroutines which are executed outside of the normal course of operation. Events that can be trapped are:

Time intervals (ON TIMER)
Keypresses (ON KEY)
Serial port input (ON COM)
Music queue exhaustion (ON PLAY)
Joystick triggers (ON STRIG)
Mouse activation (ON MOUSE)

Event trapping subroutines are defined as regular subroutines. At the RETURN statement, the normal course of program execution is resumed. Event trapping can be switched on and off or paused temporarily with statements of the form MOUSE ON, MOUSE OFF, MOUSE STOP. Event trapping only takes place during program execution and is paused while the program is in an error trap. If an event occurs while event-trapping is paused, then the event is triggered immediately when event trapping is resumed.

Statement	Description
COM	Manage serial port event trapping.
KEY	Manage keyboard event trapping.
KEY	Define key to trap in keyboard event trapping.
ON	Define event-trapping subroutine.
PEN	Manage light pen event trapping.
PLAY	Manage music queue event trapping.
STRIG	Manage joystick event trapping.
TIMER	Manage timer event trapping.

Error handling

Normally, any error will interrupt program execution and print a message on the console (exceptions are Overflow and Division by zero, which print a message but do not interrupt execution). It is possible to handle errors more graciously by setting an error-handling routine with the ON ERROR GOTO line_number statement. The error-handling routine starts at the given line number line_number and continues until a RESUME statement is encountered. Error trapping is in effect both when a program is running and in direct mode. Error trapping is switched off with the ON ERROR GOTO 0 statement. If an error occurs, or error trapping is switched off, while the program is executing an error-trapping routine, the program terminates and an error message is shown.

Statement	Description
ERROR	Raise an error.
ON ERROR	Define an error handler.
RESUME	End error handler and return to normal execution.

Function	Description
ERR	Error number of last error.
ERL	Line number of last error.

User-defined functions

Statement	Description
DEF FN	Define a new function.

Function	Description
FN	User-defined function.

Date and time

Statement	Description
DATE$	Set the system date.
TIME$	Set the system time.

Function	Description
DATE$	System date as a string.
TIME$	System time as a string.
TIMER	System time in seconds since midnight.

Including data in a program

Statement	Description
DATA	Define data to be used by the program.
READ	Retrieve a data entry.
RESTORE	Reset the data pointer.

Memory and machine ports

Only selected memory ranges are accessible in SE Basic IV. There is read and write support for video memory, font RAM and selected locations of the low memory segment, including the keyboard buffer. Additionally, there is read and write support for variable, array and string memory. Writing into the program code is permitted but not recommended. All ports including keyboard input and video modes are supported.

Statement	Description
BLOAD	Load a binary file into memory.
BSAVE	Save a memory region to file.
CLEAR	Clears BASIC memory.
DEF SEG	Set the memory segment.
OUT	Write a byte to a machine port.
POKE	Write a byte to a memory location.
WAIT	Wait for a value on a machine port.

Function	Description
FRE	Amount of free memory.
INP	Byte at machine port.
PEEK	Byte at memory address.
VARPTR	Memory address of variable
VARPTR$	Byte representation of length and memory address of variable

Legacy feature support

To imporve compatibility with legacy programs, SE Basic IV includes a preprocessor that attempts to convert MS BASIC syntax into SE Basic IV syntax. It applies the following conversions:

MS BASIC	SE Basic IV	Description
`><`, `=>`, `=<`	`<>`, `<=`, `>=`	not equal to, less than or equal to, greater than or equal to.
`[`, `]`	`(`, `)`	used when defining arrays.
`&H`,`&O`	`$`,`@`	hexadecimal and octal notation.
`ATN(n)`	`ATAN(n)`
`COLOUR`	`COLOR`	alternative spelling.
`ELSE`	`:ELSE`	a colon is required before an `ELSE` except if it is the first statement in a line.
`FNa`	`FN a`	a space is required after `FN`.
`HEX$(n)`, `OCT$(n)`	`STR$(n, {16\|8})`	hexadecimal or octal string.
`RND(n)`	`RND`	parameters are not accepted with `RND`.
`SPACE$(n)`	`STRING$(n,32)`	string of `n` spaces.
`THEN n`	`THEN GOTO n`	`n` cannot be an expression.
`TRON`, `TROFF`	`TRACE {ON\|OFF}`

Features not yet implemented

Features that are planned but not yet implemented are missing links to the language reference.

Unsupported features

SE Basic IV has direct access to all areas of memory and all devices. You can use machine-code subroutines to perform tasks for which it does not provide support. However, programs written for a different architecture, such as 8086, will not run.

It is not necessary, or possible, to define variable types. Like the 6502 versions of Microsoft BASIC, floating-point numbers are always stored in 40-bit MBF form. Unlike Microsoft BASIC, integers in the range [-65536 to 65535] are always stored as integers (also in 40-bits).