path: root/ossintbas_content.rst

DESCRIPTION
===========

OSS Integer BASIC is a BASIC interpreter from OSS, similar to BASIC XL
and BASIC XE. It was never released as a commercial product, and was
eventually released into the Public Domain.

It appears to be complete and free of major bugs. There is no manual
for it, so I'm documenting the differences between Integer BASIC and
BASIC XL/XE here, as I discover them.

For more info on the release:

  https://forums.atariage.com/topic/257029-oss-d-day-part-3-integer-basic-source-code-now-in-pd/

NUMERICS
========

All numbers are signed 16-bit integers. There is no floating point support
at all.

Two's complement is used, so bit 15 is the sign bit, and *-1* is
represented as *$FFFF*.

The range is *-32768* to *32767*. Somewhat confusingly (but also
usefully), positive numbers in the range *32768* to *65535* can be
entered in program code, or as response to **INPUT**, etc... but when
they are **PRINT**\ed, they will appear as negative numbers. This
is unlike Apple's Integer BASIC, for instance. It was probably done
so that BASIC code could use the familiar memory locations. Example:
**PEEK(53279)** to read the console keys. It would be very annoying if
this had to be written as **PEEK(-12257)**\... although it does work
if written that way (Apple-style).

Although floating point is not supported, it's possible to enter
numbers with a decimal point or even scientific notation. These will
silently be converted to integers, with rounding. If the result is
outside the range *-32768* to *65535*, you'll get an **ERROR- 3**.
This applies to numbers entered as part of the program as well as
those entered in response to **INPUT**, or **READ** from **DATA**
lines.

COMMANDS
========

**VBLANKWAIT**

  Pause and wait for a vertical blank interrupt to occur.

  Abbreviation: **V.**

**VINC** *<var>*

  Increment (add 1 to) a variable. This is about 30% faster than
  **A=A+1**.

  Abbreviation: **VI.**

**VDEC** *<var>*

  Decrement (subtract 1 from) a variable. Faster than **A=A-1**.

  Abbreviation: **VD.**

**VCONST** *<num>*, *<var>*

  Add a constant to *var*. There are 8 constants, numbered 0 through
  7. They are set with the **SET** command, using arguments 16 to 23
  to set the constants. Example: **SET 16,10** sets constant 0 to 123,
  and **VCONST 0,A** adds 10 to A.

  If *<num>* is greater than 7, the variable will be
  unchanged. **SET** won't accept a number higher than 23 for its first
  argument, so there'd be no way to set any constants other than 0
  to 7 anyway.

  When Integer BASIC first starts up, the constants are initialized
  to what amounts to garbage values. You can examine them with
  **SYS(16)** through **SYS(23)**, but it's a bad idea to depend on
  them because the values are different between the disk and cartridge
  versions of Integer BASIC.

  Using VCONST is about 15% faster than just adding a number to a
  variable.

  Abbreviation: **VC.**


FUNCTIONS
=========

**RUN(0)**

  Returns the run (coldstart) address of the interpreter. **? USR(RUN(0))**
  restarts Integer BASIC. The *0* is a 'dummy' argument (ignored, like **FRE(0)**\).

OPERATORS
=========

**!**

  Binary OR. Infix operator.

**&**

  Binary AND. Infix operator.

**%**

  Binary exclusive OR (XOR). Infix operator.

**<<**

  Left shift, like C. Infix operator. Result is the expression on the left,
  shifted left by the number of bits on the right. Examples: **1<<4**
  is 16, **255<<1** is 510.

  Bits shifted off the left end of the number are lost. Zeroes are
  shifted in, for the low-order bit(s). Shifting anything left 16 times
  results in zero. Since bit 15 is the sign bit, shifting a 1 into bit
  15 will result in a negative number.

**>>**

  Right shift, like C. Infix operator. Result is the expression
  on the left, shifted to the right, by the number of bits on the
  right. Examples: **16>>4** is 1, **255>>1** is 127.

  Bits shifted off the right end of the number are lost. Zeroes are
  shifted in, for the high-order bit(s). Shifting any negative number
  to the right will result in a positive numbers, since a zero will be
  shifted into the sigh bit.

**^&**

  Binary NAND. Like AND, but inverts the bits in the result. Infix operator.

**^!**

  Binary NOR. Infix operator.

**^%**

  Binary NXOR. Infix operator.

**\\**

  Modulus. Infix operator. Result of **X&Y** is the remainder of **X/Y**.

  *NOTE* that this is **broken** in the cartridge version of Integer BASIC,
  though it works correctly in the disk version. See **BUGS**, below.


COMPATIBILITY
=============

Integer BASIC can't LOAD programs that were SAVEd by any other BASIC,
and programs SAVEd by Integer BASIC can't be LOADed in any other
BASIC. Use LIST and ENTER instead.

Actually, the disk and cartridge versions of Integer BASIC can't even
LOAD each others' programs. They use a different set of token numbers.
This is because the cartridge version includes the **HITCLR** command,
but the disk version does not.

The **INT()** function exists in Integer BASIC, but it doesn't actually
do anything. Seems to be provided for compatibility with other BASICs.

Missing Commands
----------------

Integer BASIC has the full command set of the BASIC XL cartridge,
minus these commands:

**DEG** **RAD** **RGET** **RPUT**

The cartridge version of Integer BASIC has the **HITCLR** command
(from BASIC XE), but the disk version does not.

The BASIC XL extension disk commands (**LOCAL**, **EXIT**,
**PROCEDURE**, **CALL**, **SORTUP**, and **SORTDOWN**) don't exist in
Integer BASIC. If there was ever an extensions disk for Integer BASIC,
nobody's found it yet.

The extra commands in BASIC XE (**EXTEND**, **INVERSE**, **NORMAL**,
**BLOAD**, and **BSAVE**) are not supported.

Missing Operators/Functions
---------------------------

**^**
  There is no exponentiation operator; **2^2** is a syntax error.

**ATN()**, **CLOG()**, **COS()**, **EXP()**, **LOG()**, **SIN()**
  There are no trigonometric functions in Integer BASIC. These can
  be used as array variable names, if you wish.

**USING**
  BASIC XL and XE's "PRINT USING" doesn't exist in Integer BASIC.

PERFORMANCE
===========

OSS Integer BASIC is *fast*, compared to other interpreted BASICs on
the Atari. It even outperforms Turbo BASIC XL (though, not *compiled*
Turbo).

For testing, I used a modified version of the Sieve of Eratosthenes
program, found in the source for **bas55**. The program finds and
prints all the prime numbers between 2 and 1000. The code::

  10 POKE 18,0:POKE 19,0:POKE 20,0
  20 DIM A(1000)
  30 N=1000
  100 S=SQR(N)
  110 FOR I=2 TO S
  120 IF A(I)=1 THEN 170
  130 D=N/I
  140 FOR J=I TO D
  150 A(I*J)=1
  160 NEXT J
  170 NEXT I
  180 FOR I=2 TO N
  190 IF A(I)=1 THEN 210
  200 PRINT I
  210 NEXT I
  1000 PRINT PEEK(18)*256*256+PEEK(19)*256+PEEK(20)

Line 1000 prints how many jiffies the program took to run. I used
Atari800 5.2.0 emulating an NTSC Atari 800XL, so one jiffy is 1/60 of
a second. The "Fastchip" results use Charles Marslet's OS floating
point replacement ROM. For Integer BASIC, BASIC XL and BASIC XE,
separate runs were done with the line **5 FAST** at the start of the
program. Results:

.. csv-table::

  "BASIC", "Jiffies", "Speedup"
  "Atari 8K", "1867", "--"
  "A+", "1671", "1.12"
  "Atari 8K (Fastchip)", "1587", "1.18"
  "A+ (Fastchip)", "1569", "1.19"
  "XE", "1440", "1.3"
  "AMSB2", "1518", "1.23"
  "XL", "1270", "1.47"
  "Altirra", "1166", "1.67"
  "XL (FAST)", "1110", "1.68"
  "XL (Fastchip)", "1049", "1.78"
  "XL (Fastchip, FAST)", "887", "2.1"
  "Turbo", "825", "2.3"
  "XE (FAST)", "777", "2.4"
  "XE (Fastchip, FAST)", "777", "2.4"
  "Altirra (Fastchip)", "769", "2.43"
  "Integer", "719", "2.6"
  "Integer (FAST)", "575", "3.25"

Turbo BASIC XL, Atari Microsoft BASIC, and OSS Integer BASIC run at
the same speed with or without the Fastchip ROM, since they don't use
the OS floating point routines.

For reference, I rewrote the program in C and compiled it with
cc65. It runs in 349 jiffies, 5.35x as fast as BASIC, with or without
the Fastchip ROM. Since cc65 only supports integer arithmetic, this
probably represents the theoretical maximum speed the algorithm could
run in on the Atari, without rewriting it in assembly. By comparison,
Integer BASIC looks pretty good.

If you get rid of lines 180 to 210 (don't print the results), Integer
BASIC with FAST runs it in 245 jiffies, and the equivalent C program
runs in 61 jiffies. This shows that CIO and the E: device are the
"bottleneck" for this program (and that compiled C is still faster
than anything interpreted).


BUGS
====

Modulo Arithmetic
-----------------

The **\\** (modulus) operator returns incorrect results in the
cartridge version of Integer BASIC. This program demonstrates the
bug::

  10 For I=1 To 10
  20   ? I,I\3,I-(I/3)*3
  30 Next I

When run with the disk version, the results are correct::

  1         1         1
  2         2         2
  3         0         0
  4         1         1
  5         2         2
  6         0         0
  7         1         1
  8         2         2
  9         0         0
  10        1         1

The same program run with the cartridge version gives::

  1         254       1
  2         255       2
  3         0         0
  4         1         1
  5         2         2
  6         253       0
  7         254       1
  8         255       2
  9         0         0
  10        1         1

This is obviously wrong.

If you're writing a real program in Integer BASIC, I recommend
avoiding the **\\** operator entirely. Write something like **X-X/Y\*Y**
instead.