Skip to content

Language guide

Jump to bottom
cheveron edited this page Feb 24, 2022 · 30 revisions

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

This documentation is copyright © 2012-2022 Source Solutions, Inc. Portions copyright © 2014-2019 Rob Hagemans.
Licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Quick start guide

User's guide

Configuration guide

Language guide

Language reference

Technical reference

Developer's guide

Acknowledgments

License

Clone this wiki locally