Supported functions and statements

BASCOMP 2.2 Supported Language Features

Notes:

Numeric values are 16-bit integer-style values.
Strings are counted runtime strings with a maximum payload length of 255 bytes.
File channels are 1 to 9.
Array indexes are 1-based.

Supported Statements

REM and apostrophe comments:

REM This is a comment
' This is also a comment

LET and implicit assignment without LET:

LET A = 10
A = A + 1
A$ = "HELLO"

INPUT ["prompt"], var
INPUT ["prompt"], var$
! var as shorthand for INPUT var

INPUT "NAME", N$
INPUT "VALUE", A
! A

LINE INPUT #channel, var$

LINE INPUT #1, A$

PRINT
? as shorthand for PRINT
PRINT #channel, ...

PRINT "HELLO"
? A
PRINT #2, "VALUE="; A

IF ... THEN ... ELSE ...
multi-line IF ... THEN, ELSEIF ... THEN, ELSE, END IF
GOTO
GOSUB + RETURN
ON expression GOTO ... — available since BASCOMP 2.1
ON expression GOSUB ... — available since BASCOMP 2.1

ON A GOTO START, MIDDLE, FINISH
ON A GOSUB SUB1, SUB2, SUB3

FOR ... TO ... [STEP ...] / NEXT
END FOR
EXIT FOR — available since BASCOMP 2.1
WHILE ... / WEND
DIM for integer arrays
DIM name$ AS STRING * length — available since BASCOMP 2.1
DIM name$(count) AS STRING * maxLength — available since BASCOMP 2.1
OPEN ... FOR INPUT AS #channel
OPEN ... FOR OUTPUT AS #channel
CLOSE #channel
KILL
GET #channel, [position,] variable
PUT #channel, [position,] variable
CHDIR path$ — available since BASCOMP 2.1
MKDIR path$ — available since BASCOMP 2.1
RMDIR path$ — available since BASCOMP 2.1
FILES [filespec$] — available since BASCOMP 2.1
CLS
LOCATE row, column
COLOR foreground, background
SCREEN mode — available since BASCOMP 2.1
PSET x, y, color — available since BASCOMP 2.1
LINE (x1,y1)-(x2,y2), color [,B|BF] — available since BASCOMP 2.1
CIRCLE (x,y), radius [,color][,,,aspect] — aspect parameter available since BASCOMP 2.2
BEEP — available since BASCOMP 2.1
DEF SEG
DEF SEG = expression
POKE offset, value
POKE segment, offset, value — available since BASCOMP 2.1
OUT port, value — available since BASCOMP 2.1
CALLINT interruptNumber, registerArray — available since BASCOMP 2.1
SELECT CASE, CASE, CASE ELSE, END SELECT
RANDOMIZE
RANDOMIZE TIMER / numeric-expression
RANDOMIZE TIMER() — available since BASCOMP 2.1
DATA — available since BASCOMP 2.1
READ — available since BASCOMP 2.1
RESTORE — available since BASCOMP 2.1
DATAB — available since BASCOMP 2.1
CALLDATA lineNumber — available since BASCOMP 2.1
XSET handle, index, string-expression
XFREE handle
END [errorlevel] / STOP / . as shorthand — optional END errorlevel available since BASCOMP 2.2

Supported Control Structures

IF / ELSE

BASCOMP supports single-line and multi-line IF forms in both traditional numbered BASIC mode and QB-style unnumbered mode.

Single-line form:

IF A > 10 THEN PRINT "HIGH" ELSE PRINT "LOW"

Multi-line form:

IF A > 10 THEN
  PRINT "HIGH"
ELSEIF A = 10 THEN
  PRINT "TEN"
ELSE
  PRINT "LOW"
END IF

Boolean IF expressions support AND, OR, and NOT in supported comparison contexts.

IF A > 0 AND B > 0 THEN PRINT "BOTH POSITIVE"
IF NOT A = 0 THEN PRINT "A IS NOT ZERO"

SELECT CASE

SELECT CASE supports numeric selection logic.

SELECT CASE A
  CASE 1
    PRINT "ONE"
  CASE 2
    PRINT "TWO"
  CASE ELSE
    PRINT "OTHER"
END SELECT

Current CASE handling is based on individual numeric case values and CASE ELSE.

FOR / NEXT / END FOR / EXIT FOR

Counted loops are supported, including nested loops and optional STEP values.

FOR I = 1 TO 10 STEP 2
  PRINT I
NEXT I

END FOR is recognized as an explicit loop terminator form.

EXIT FOR leaves the innermost active FOR loop. EXIT FOR is available since BASCOMP 2.1.

FOR I = 1 TO 10
  IF I = 5 THEN EXIT FOR
  PRINT I
END FOR

WHILE / WEND

A = 0

WHILE A < 10
  A = A + 1
WEND

ON GOTO / ON GOSUB

ON expression GOTO and ON expression GOSUB are available since BASCOMP 2.1. They use a 1-based target index.

A = 2
ON A GOTO ONE, TWO, THREE

ONE:
PRINT "ONE"
END

TWO:
PRINT "TWO"
END

THREE:
PRINT "THREE"
END

A = 1
ON A GOSUB SUB1, SUB2
END

SUB1:
PRINT "SUB1"
RETURN

SUB2:
PRINT "SUB2"
RETURN

Subroutines

Subroutines are supported through GOSUB and RETURN.

GOSUB HELLO
END

HELLO:
PRINT "HELLO"
RETURN

END [errorlevel]

END without an argument terminates the program with errorlevel 0. END with a numeric expression terminates the program with that value as DOS errorlevel.

END
END 1

Supported Data Types

Numeric Variables

Numeric variables store signed 16-bit integer-style values.

A = 123
B = -10
C = A + B

String Variables

String identifiers end with $ and use counted string representation in the runtime.

A$ = "HELLO"
B$ = A$ + " WORLD"

Fixed-length string storage is available since BASCOMP 2.1:

DIM NAME$ AS STRING * 40
NAME$ = "BASCOMP"

Indexed Numeric Arrays

DIM creates indexed numeric arrays using syntax such as A(I). Array indexes are 1-based in the runtime.

DIM A(10)

A(1) = 5
A(2) = A(1) + 10

PRINT A(2)

Small arrays are stored internally. Larger numeric arrays are backed by external DOS memory through the runtime array support.

External String Arrays

External string arrays are available through XALLOC and through the DIM syntax introduced in BASCOMP 2.1.

Be careful: The maximum size of any individual external string array is 65536 bytes. In the case of strings, this means: (stringlen + 1) * stringnums <= 65536.

DIM-style external string arrays — available since BASCOMP 2.1

DIM NAMES$(10) AS STRING * 40

NAMES$(1) = "ALICE"
NAMES$(2) = "BOB"

PRINT NAMES$(1)

Handle-style external string arrays

H = XALLOC(10, 40)

XSET H, 1, "ALICE"
XSET H, 2, "BOB"

PRINT XGET$(H, 1)

XFREE H

XALLOC(count) uses the default maximum string length. XALLOC(count, maxLength) specifies the per-entry maximum payload length.

Supported Expressions

Numeric Expressions

Numeric expressions support:

decimal constants
hexadecimal constants with &H...
numeric variables
numeric array elements such as A(I)
parentheses
unary +
unary -
unary NOT
"+"
"-"
"*"
"/"
"\"
MOD
XOR
AND
OR
exponentiation with ^
numeric function calls

Examples:

A = 10 + 20 * 3
B = (A - 5) \ 2
C = A MOD 7
D = &HFF
E = NOT 0
F = 2 ^ 8

Negative exponents are not supported and cause a runtime error. Overflow is not checked.

String Expressions

String expressions support:

string variables
string literals
string concatenation with +
string function calls
indexed external string array access
DATE$
TIME$
INKEY$
INPUT$
COMMAND$
PROGDIR$
HEX$
SPACE$
STRING$

Examples:

A$ = "HELLO"
B$ = A$ + " WORLD"

C$ = LEFT$(B$, 5)
D$ = STR$(123)
E$ = DATE$
F$ = TIME$

Nested string expressions and concatenations are supported through the internal string-expression parser and temporary string buffers.

Supported Comparisons

The following comparison operators are supported in IF expressions:

"="
"<>"
"<"
">"
"<="
">="

Comparisons work for both numeric values and supported string expressions, depending on context.

IF A = 10 THEN PRINT "TEN"
IF A$ = "OK" THEN PRINT "MATCH"
IF LEFT$(A$, 1) = "Y" THEN PRINT "YES"

Supported Functions

Numeric and Conversion Functions

LEN(string)

Returns the length of a string.

A$ = "HELLO"
PRINT LEN(A$)

VAL(string)

Converts a string to a numeric value.

A$ = "123"
A = VAL(A$)

ASC(string)

Returns the character code of the first character.

A = ASC("A")
PRINT A

EOF(channel)

Returns the end-of-file state for a file channel.

OPEN "TEST.TXT" FOR INPUT AS #1

WHILE EOF(1) = 0
  LINE INPUT #1, A$
  PRINT A$
WEND

CLOSE #1

EXIST(string)

Tests whether a file exists.

IF EXIST("TEST.TXT") THEN PRINT "FILE EXISTS"

INSTR(string, pattern)

Searches for a substring and returns its position.

P = INSTR("ABCDEF", "CD")
PRINT P

INSTR(start, string, pattern)

Searches for a substring starting at a specific position.

P = INSTR(3, "ABABAB", "AB")
PRINT P

ABS(number)

Returns the absolute value.

PRINT ABS(-10)

SGN(number)

Returns -1, 0, or 1 depending on the sign of the value.

PRINT SGN(-20)
PRINT SGN(0)
PRINT SGN(20)

RND(number)

Returns a pseudo-random number from 1 to n. If n <= 0, the runtime returns 0.

RANDOMIZE TIMER
A = RND(100)
PRINT A

INT(number)

Returns the integer value. Since BASCOMP numeric values are already integer-style values, this is mainly useful for compatibility.

A = INT(123)

SQR(number)

Returns the integer square root.

PRINT SQR(100)

MIN(a, b)

Returns the smaller value.

PRINT MIN(10, 20)

MAX(a, b)

Returns the larger value.

PRINT MAX(10, 20)

TIMER()

Returns the number of seconds since midnight modulo 65536.

T = TIMER()
PRINT T

EXEC(program$, args$)

Starts a DOS child program and returns 0 on success or a DOS error code.

R = EXEC("CHILD", "")
IF R <> 0 THEN PRINT "EXEC ERROR "; R

Example with arguments:

R = EXEC("TOOL", "INPUT.TXT OUTPUT.TXT")
PRINT R

CPUID()

Detects the CPU class and returns the runtime CPU identifier.

Typical return values include:

86 for 8086/8088 class
120 for NEC V20/V30 class
186 for 80186/80188 class
286
386
486
586
686
1500 for CPUID family F
999 for CPUID-present but otherwise unmapped family

C = CPUID()
PRINT "CPU="; C

PEEK(offset)

Reads a byte from the active DEF SEG segment.

DEF SEG = &HB800
A = PEEK(0)
DEF SEG

PEEK(segment, offset)

Reads a byte from an explicit segment and offset. This form is available since BASCOMP 2.1.

A = PEEK(&HB800, 0)
PRINT A

INP(port)

Reads a byte from an I/O port. INP() is available since BASCOMP 2.1.

A = INP(&H60)
PRINT A

XALLOC(count)

Allocates an external string array with default maximum string length and returns a handle.

H = XALLOC(10)

XALLOC(count, maxLength)

Allocates an external string array with a specific maximum string length.

H = XALLOC(10, 40)
XSET H, 1, "HELLO"
PRINT XGET$(H, 1)
XFREE H

String-Producing Functions

CHR$(number)

Builds a one-character string from a character code.

A$ = CHR$(65)
PRINT A$

COMMAND$

Returns the DOS command tail passed to the program.

A$ = COMMAND$
PRINT A$

If the command tail starts with one leading space, the runtime strips that one leading space.

HEX$(number)

Converts a 16-bit value to an uppercase hexadecimal string without leading zeroes.

A$ = HEX$(255)
PRINT A$

LEFT$(string, count)

Returns the left part of a string.

PRINT LEFT$("HELLO", 2)

MID$(string, start, count)

Returns a substring.

PRINT MID$("HELLO", 2, 3)

PROGDIR$

Returns the directory of the currently running COM program.

PRINT PROGDIR$

Examples of possible values:

"C:\TOOLS" for "C:\TOOLS\PROGRAM.COM"
"C:" for "C:PROGRAM.COM"
"" if no path information is available

RIGHT$(string, count)

Returns the right part of a string.

PRINT RIGHT$("HELLO", 2)

SPACE$(count)

Returns a string containing count spaces.

PRINT "A"; SPACE$(5); "B"

STRING$(count, charCode)

Returns a string containing count repetitions of the character with the given character code.

PRINT STRING$(10, 42)

LTRIM$(string)

Removes leading spaces.

PRINT LTRIM$("   HELLO")

RTRIM$(string)

Removes trailing spaces.

PRINT RTRIM$("HELLO   ")

TRIM$(string)

Removes leading and trailing spaces.

PRINT TRIM$("   HELLO   ")

UCASE$(string)

Converts ASCII lowercase letters a to z to uppercase.

PRINT UCASE$("Hello")

STR$(number)

Converts a numeric value to a string.

A$ = STR$(123)
PRINT A$

XGET$(handle, index)

Reads a string from an external string array.

H = XALLOC(5, 20)
XSET H, 1, "ONE"
PRINT XGET$(H, 1)
XFREE H

DATE$

Returns the DOS date in mm-dd-yyyy format.

PRINT DATE$

TIME$

Returns the DOS time in hh:mm:ss format.

PRINT TIME$

INKEY$

Returns a non-blocking keyboard input string.

K$ = INKEY$
IF LEN(K$) <> 0 THEN PRINT "KEY PRESSED"

Special keys return a two-character string where the first byte is zero and the second byte is the scan code. Enhanced keyboard variants are normalized by the runtime. If no key is available, INKEY$ returns an empty string.

INPUT$

Reads a string from standard input.

A$ = INPUT$
PRINT A$

DATA, READ, RESTORE, DATAB, and CALLDATA

DATA, READ, RESTORE, DATAB, and CALLDATA are all available since BASCOMP 2.1.

DATA

Defines numeric word data.

DATA 10,20,30

READ A
READ B
READ C

PRINT A; B; C

READ

Reads the next numeric word from DATA.

DATA 100,200

READ A
READ B

RESTORE

Resets the runtime data pointer to the first DATA record.

DATA 1,2,3

READ A
READ B

RESTORE

READ C
PRINT C

DATAB

Defines raw byte data in the generated assembly.

100 DATAB 65,66,67

CALLDATA lineNumber

Calls the byte block generated by DATAB at the given BASIC source line number and executes them as machine code!

This is an advanced low-level feature. The byte block is treated as machine code and must return correctly, typically with RET, decimal opcode 195, if it is called as a subroutine.

Please note: DATA is only being executed if you follow these two steps:

You use DATAB (not DATA itself), and
You explicitly call CALLDATA.

In all other cases, DATA entries will just be skipped during execution! This is a safety precaution.

Minimal safe example:

100 DATAB 195
110 CALLDATA 100
120 PRINT "RETURNED"

File I/O

Text file I/O is supported through:

OPEN
CLOSE
PRINT #
LINE INPUT #

OPEN "OUT.TXT" FOR OUTPUT AS #1
PRINT #1, "HELLO"
CLOSE #1

OPEN "OUT.TXT" FOR INPUT AS #1
LINE INPUT #1, A$
PRINT A$
CLOSE #1

Binary file I/O is supported through:

GET
PUT

OPEN "DATA.BIN" FOR OUTPUT AS #1
A = 65
PUT #1, 1, A
CLOSE #1

OPEN "DATA.BIN" FOR INPUT AS #1
GET #1, 1, A
PRINT A
CLOSE #1

File channels 1 to 9 are supported.

OPEN supports:

FOR INPUT
FOR OUTPUT

KILL deletes a file:

KILL "OLD.TXT"

EXIST() checks whether a file is present:

IF EXIST("OLD.TXT") THEN KILL "OLD.TXT"

The runtime retains buffered byte output for PUT; buffered binary output is flushed when required by handle changes, seek operations, close operations, and mixed text/binary output paths.

Directory and File Listing Support

Directory and file listing statements are available since BASCOMP 2.1.

CHDIR

Changes the current directory.

CHDIR "C:\TEMP"

MKDIR

Creates a directory.

MKDIR "TESTDIR"

RMDIR

Removes a directory.

RMDIR "TESTDIR"

FILES

Lists matching files.

FILES
FILES "*.BAS"

Directory entries are printed in brackets by the runtime.

Screen Output and Text Mode Control

Standard text output is supported through PRINT.

Additional screen control is provided by:

CLS
LOCATE
COLOR

CLS
COLOR 14, 1
LOCATE 10, 20
PRINT "HELLO"

COLOR foreground, background sets the active text attribute used by BIOS-style console output when screen output support is active.

Graphics Support

Graphics statements are available since BASCOMP 2.1.

SCREEN mode

SCREEN selects a BIOS video mode through the runtime.

Known mappings:

SCREEN 0 maps to BIOS text mode 03h
SCREEN 1 maps to BIOS mode 04h
SCREEN 2 maps to BIOS mode 06h
Other values are passed as BIOS mode numbers in AL; for example, SCREEN 13 selects BIOS mode 13h on systems that support it.

Examples:

SCREEN 0
PRINT "TEXT MODE"

SCREEN 13
PSET 160, 100, 12

PSET x, y, color

Plots one pixel using BIOS graphics output.

SCREEN 13
PSET 160, 100, 15

LINE (x1,y1)-(x2,y2), color

Draws a line.

SCREEN 13
LINE (10,10)-(200,100), 15

LINE (x1,y1)-(x2,y2), color, B

Draws a rectangle outline.

SCREEN 13
LINE (20,20)-(120,80), 14, B

LINE (x1,y1)-(x2,y2), color, BF

Draws a filled rectangle.

SCREEN 13
LINE (30,30)-(100,70), 4, BF

CIRCLE (x,y), radius [,color][,,,aspect]

Draws an outline circle. With the optional aspect parameter, CIRCLE can draw an aspect-scaled ellipse.

SCREEN 13
CIRCLE (160,100), 50, 15
CIRCLE (160,100), 50, 15,,,128

Sound

BEEP

BEEP is available since BASCOMP 2.1. It outputs the bell character.

BEEP

Memory Access

BASCOMP 2.1 supports a compact BASIC-style memory access subset.

DEF SEG = expression

Sets the active segment used by PEEK(offset) and POKE offset,value.

DEF SEG = &HB800
A = PEEK(0)
DEF SEG

DEF SEG

Resets the active segment to the program segment.

DEF SEG

PEEK(offset)

Reads a byte from the active DEF SEG segment.

DEF SEG = &HB800
A = PEEK(0)

PEEK(segment, offset)

Reads a byte from an explicit segment and offset. This form is available since BASCOMP 2.1.

A = PEEK(&HB800, 0)

POKE offset, value

Writes a byte to the active DEF SEG segment and offset.

DEF SEG = &HB800
POKE 0, 65
DEF SEG

POKE segment, offset, value

Writes a byte to an explicit segment and offset. This form is available since BASCOMP 2.1.

POKE &HB800, 0, 65

Values written by POKE must fit into a byte, 0..255; otherwise the runtime raises a byte value error.

Port I/O

Port I/O is available since BASCOMP 2.1.

INP(port)

Reads one byte from an I/O port.

A = INP(&H60)
PRINT A

OUT port, value

Writes one byte to an I/O port.

OUT &H61, 0

The output value must fit into a byte, 0..255.

Interrupt Calls

CALLINT interruptNumber, registerArray

CALLINT is available since BASCOMP 2.1. It calls a real-mode interrupt using a numeric register array.

The array layout is:

regs(1) = AX
regs(2) = BX
regs(3) = CX
regs(4) = DX
regs(5) = SI
regs(6) = DI
regs(7) = FLAGS output only

Segment registers are not user-settable in this minimal runtime interface.

Example: call BIOS keyboard interrupt 16h, function 00h, to wait for and read a key.

DIM R(7)

R(1) = &H0000
R(2) = 0
R(3) = 0
R(4) = 0
R(5) = 0
R(6) = 0

CALLINT &H16, R

PRINT "AX="; R(1)
PRINT "FLAGS="; R(7)

Example: BIOS keyboard status, interrupt 16h, function 01h.

DIM R(7)

R(1) = &H0100

CALLINT &H16, R

IF R(7) AND &H40 THEN
  PRINT "NO KEY AVAILABLE"
ELSE
  PRINT "KEY AVAILABLE"
END IF

&H40 checks the zero flag bit in the returned FLAGS word.

System Strings, Date, Time, Keyboard, EXEC, and CPU Support

BASCOMP includes runtime support for:

COMMAND$ for reading the DOS command tail
PROGDIR$ for reading the directory of the running COM program
DATE$ using DOS date services
TIME$ using DOS time services
TIMER() using DOS time services
INKEY$ using BIOS keyboard calls
EXEC() for launching DOS child programs
CPUID() for CPU-class detection

Examples:

PRINT DATE$
PRINT TIME$
PRINT TIMER()

K$ = INKEY$
IF LEN(K$) <> 0 THEN PRINT "KEY"

R = EXEC("CHILD", "")
IF R <> 0 THEN PRINT "EXEC ERROR "; R

PRINT CPUID()

Memory Usage

The compiled COM program, including generated code, numeric variables, fixed runtime data, and statically allocated strings, must fit into the normal COM program image limit. In practice, the currently compiled program including variables and static strings can be at most 65,280 bytes.

At runtime, BASCOMP can allocate additional DOS memory through the runtime array support. This applies especially to larger numeric arrays and external string arrays. These allocations are performed while the program is running and can use additional conventional DOS memory beyond the initial COM image, up to the amount available from DOS.

EMS and XMS memory are currently not supported.

External string arrays

External string arrays store each string element in a fixed-size slot. Each slot consists of one length byte plus the configured maximum payload length.

Therefore, the maximum memory requirement is:

(maxLength + 1) * elementCount <= 65536

The runtime supports external string array handles and checks the allocation size at runtime. maxLength can be 1 to 255 bytes. The element count is 1-based and limited by the runtime allocation rules.

Examples:

Declaration / allocation style	Slot size	Maximum element count within 64 KiB
`DIM A$(32767) AS STRING * 1`	2 bytes	32767 elements
`DIM A$(7281) AS STRING * 8`	9 bytes	7281 elements
`DIM A$(3855) AS STRING * 16`	17 bytes	3855 elements
`DIM A$(1598) AS STRING * 40`	41 bytes	1598 elements
`DIM A$(1008) AS STRING * 64`	65 bytes	1008 elements
`DIM A$(512) AS STRING * 127`	128 bytes	512 elements
`DIM A$(256) AS STRING * 255`	256 bytes	256 elements

The same size rule applies to handle-style external string arrays allocated with XALLOC(count, maxLength).

Integer arrays

Numeric arrays store 16-bit integer-style values, so each element requires 2 bytes.

Small numeric arrays are stored internally by the generated program. Larger numeric arrays are backed by external DOS memory through the runtime array support.

For external integer arrays, the practical maximum element count is 32767 elements:

32767 elements * 2 bytes = 65534 bytes

This keeps one external integer array within one 64 KiB allocation block.

Examples:

Array size	Payload size
`DIM A(100)`	200 bytes
`DIM A(1000)`	2000 bytes
`DIM A(10000)`	20000 bytes
`DIM A(32767)`	65534 bytes

As with external string arrays, this memory is allocated at runtime from conventional DOS memory and is not part of the initial COM program image.

Compatibility Notes and Limits

BASCOMP supports both numbered BASIC source mode and QB-style unnumbered source mode.
Numeric values are 16-bit integer-style values.
File channels are 1..9.
Array indexes are 1-based.
FOR/WHILE nesting depth is limited to 4.
Block IF nesting depth is limited to 4.
Numeric parser context depth is limited to 4.
String parser context depth is limited to 8.