path: root/ossintbas.7

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "OSSINTBAS" 7 "2025-03-25" "0.2.2" "Urchlay's Atari 8-bit Tools"
.SH NAME
ossintbas \- OSS Integer BASIC Notes
.SH DESCRIPTION
.sp
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.
.sp
It appears to be complete and free of major bugs. There is no manual
for it, so I\(aqm documenting the differences between Integer BASIC and
BASIC XL/XE here, as I discover them.
.sp
For more info on the release:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
https://forums.atariage.com/topic/257029\-oss\-d\-day\-part\-3\-integer\-basic\-source\-code\-now\-in\-pd/
.ft P
.fi
.UNINDENT
.UNINDENT
.SH NUMERICS
.sp
All numbers are signed 16\-bit integers. There is no floating point support
at all.
.sp
Two\(aqs complement is used, so bit 15 is the sign bit, and \fI\-1\fP is
represented as \fI$FFFF\fP\&.
.sp
The range is \fI\-32768\fP to \fI32767\fP\&. Somewhat confusingly (but also
usefully), positive numbers in the range \fI32768\fP to \fI65535\fP can be
entered in program code, or as response to \fBINPUT\fP, etc... but when
they are \fBPRINT\fPed, they will appear as negative numbers. This
is unlike Apple\(aqs Integer BASIC, for instance. It was probably done
so that BASIC code could use the familiar memory locations. Example:
\fBPEEK(53279)\fP to read the console keys. It would be very annoying if
this had to be written as \fBPEEK(\-12257)\fP\&... although it does work
if written that way (Apple\-style).
.sp
Although floating point is not supported, it\(aqs 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 \fI\-32768\fP to \fI65535\fP, you\(aqll get an \fBERROR\- 3\fP\&.
This applies to numbers entered as part of the program as well as
those entered in response to \fBINPUT\fP, or \fBREAD\fP from \fBDATA\fP
lines.
.SH COMMANDS
.sp
\fBVBLANKWAIT\fP
.INDENT 0.0
.INDENT 3.5
Pause and wait for a vertical blank interrupt to occur.
.sp
Abbreviation: \fBV.\fP
.UNINDENT
.UNINDENT
.sp
\fBVINC\fP \fI<var>\fP
.INDENT 0.0
.INDENT 3.5
Increment (add 1 to) a variable. This is about 30% faster than
\fBA=A+1\fP\&. Abbreviate as \fBVD.\fP\&.
.sp
Abbreviation: \fBVI.\fP
.UNINDENT
.UNINDENT
.sp
\fBVDEC\fP \fI<var>\fP
.INDENT 0.0
.INDENT 3.5
Decrement (subtract 1 from) a variable. Abbreviate as \fBVD.\fP\&.
.sp
Abbreviation: \fBVD.\fP
.UNINDENT
.UNINDENT
.sp
\fBVCONST\fP \fI<num>\fP, \fI<var>\fP
.INDENT 0.0
.INDENT 3.5
Add a constant to \fIvar\fP\&. There are 8 constants, numbered 0 through
7. They are set with the \fBSET\fP command, using arguments 16 to 23
to set the constants. Example: \fBSET 16,10\fP sets constant 0 to 123,
and \fBVCONST 0,A\fP adds 10 to A.
.sp
If \fI<num>\fP is greater than 7, the variable will be
unchanged. \fBSET\fP won\(aqt accept a number higher than 23 for its first
argument, so there\(aqd be no way to set any constants other than 0
to 7 anyway.
.sp
When Integer BASIC first starts up, the constants are initialized
to what amounts to garbage values. You can examine them with
\fBSYS(16)\fP through \fBSYS(23)\fP, but it\(aqs a bad idea to depend on
them because the values are different between the disk and cartridge
versions of Integer BASIC.
.sp
Using VCONST is about 15% faster than just adding a number to a
variable.
.sp
Abbreviation: \fBVC.\fP
.UNINDENT
.UNINDENT
.SH FUNCTIONS
.sp
\fBRUN(0)\fP
.INDENT 0.0
.INDENT 3.5
Returns the run (coldstart) address of the interpreter. \fB? USR(RUN(0))\fP
restarts Integer BASIC. The \fI0\fP is a \(aqdummy\(aq argument (ignored, like \fBFRE(0)\fP).
.UNINDENT
.UNINDENT
.SH OPERATORS
.sp
\fB!\fP
.INDENT 0.0
.INDENT 3.5
Binary OR. Infix operator.
.UNINDENT
.UNINDENT
.sp
\fB&\fP
.INDENT 0.0
.INDENT 3.5
Binary AND. Infix operator.
.UNINDENT
.UNINDENT
.sp
\fB%\fP
.INDENT 0.0
.INDENT 3.5
Binary exclusive OR (XOR). Infix operator.
.UNINDENT
.UNINDENT
.sp
\fB<<\fP
.INDENT 0.0
.INDENT 3.5
Left shift, like C. Infix operator. Result is the expression on the left,
shifted left by the number of bits on the right. Examples: \fB1<<4\fP
is 16, \fB255<<1\fP is 510.
.sp
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.
.UNINDENT
.UNINDENT
.sp
\fB>>\fP
.INDENT 0.0
.INDENT 3.5
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: \fB16>>4\fP is 1, \fB255>>1\fP is 127.
.sp
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.
.UNINDENT
.UNINDENT
.sp
\fB^&\fP
.INDENT 0.0
.INDENT 3.5
Binary NAND. Like AND, but inverts the bits in the result. Infix operator.
.UNINDENT
.UNINDENT
.sp
\fB^!\fP
.INDENT 0.0
.INDENT 3.5
Binary NOR. Infix operator.
.UNINDENT
.UNINDENT
.sp
\fB^%\fP
.INDENT 0.0
.INDENT 3.5
Binary NXOR. Infix operator.
.UNINDENT
.UNINDENT
.sp
\fB\e\fP
.INDENT 0.0
.INDENT 3.5
Modulus. Infix operator. Result of \fBX&Y\fP is the remainder of \fBX/Y\fP\&.
.sp
\fINOTE\fP that this is \fBbroken\fP in the cartridge version of Integer BASIC,
though it works correctly in the disk version. See \fBBUGS\fP, below.
.UNINDENT
.UNINDENT
.SH COMPATIBILITY
.sp
Integer BASIC can\(aqt LOAD programs that were SAVEd by any other BASIC,
and programs SAVEd by Integer BASIC can\(aqt be LOADed in any other
BASIC. Use LIST and ENTER instead.
.sp
Actually, the disk and cartridge versions of Integer BASIC can\(aqt even
LOAD each others\(aq programs. They use a different set of token numbers.
This is because the cartridge version includes the \fBHITCLR\fP command,
but the disk version does not.
.sp
The \fBINT()\fP function exists in Integer BASIC, but it doesn\(aqt actually
do anything. Seems to be provided for compatibility with other BASICs.
.SS Missing Commands
.sp
Integer BASIC has the full command set of the BASIC XL cartridge,
minus these commands:
.sp
\fBDEG\fP \fBRAD\fP \fBRGET\fP \fBRPUT\fP
.sp
The cartridge version of Integer BASIC has the \fBHITCLR\fP command
(from BASIC XE), but the disk version does not.
.sp
The BASIC XL extension disk commands (\fBLOCAL\fP, \fBEXIT\fP,
\fBPROCEDURE\fP, \fBCALL\fP, \fBSORTUP\fP, and \fBSORTDOWN\fP) don\(aqt exist in
Integer BASIC. If there was ever an extensions disk for Integer BASIC,
nobody\(aqs found it yet.
.sp
The extra commands in BASIC XE (\fBEXTEND\fP, \fBINVERSE\fP, \fBNORMAL\fP,
\fBBLOAD\fP, and \fBBSAVE\fP) are not supported.
.SS Missing Operators/Functions
.INDENT 0.0
.TP
.B \fB^\fP
There is no exponentiation operator; \fB2^2\fP is a syntax error.
.TP
.B \fBATN()\fP, \fBCLOG()\fP, \fBCOS()\fP, \fBEXP()\fP, \fBLOG()\fP, \fBSIN()\fP
There are no trigonometric functions in Integer BASIC. These can
be used as array variable names, if you wish.
.TP
.B \fBUSING\fP
BASIC XL and XE\(aqs "PRINT USING" doesn\(aqt exist in Integer BASIC.
.UNINDENT
.SH BUGS
.SS Modulo Arithmetic
.sp
The \fB\e\fP (modulus) operator returns incorrect results in the
cartridge version of Integer BASIC. This program demonstrates the
bug:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
10 For I=1 To 10
20   ? I,I\e3,I\-(I/3)*3
30 Next I
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When run with the disk version, the results are correct:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The same program run with the cartridge version gives:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This is obviously wrong.
.sp
If you\(aqre writing a real program in Integer BASIC, I recommend
avoiding the \fB\e\fP operator entirely. Write something like \fBX\-X/Y*Y\fP
instead.
.SH COPYRIGHT
.sp
WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
.SH AUTHOR
.INDENT 0.0
.IP B. 3
Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&.
.UNINDENT
.SH SEE ALSO
.sp
\fBa8cat\fP(1),
\fBa8eol\fP(1),
\fBa8xd\fP(1),
\fBatr2xfd\fP(1),
\fBatrsize\fP(1),
\fBaxe\fP(1),
\fBbas2aplus\fP(1),
\fBblob2c\fP(1),
\fBblob2xex\fP(1),
\fBcart2xex\fP(1),
\fBcxrefbas\fP(1),
\fBdasm2atasm\fP(1),
\fBdiffbas\fP(1),
\fBdumpbas\fP(1),
\fBf2toxex\fP(1),
\fBfenders\fP(1),
\fBlistbas\fP(1),
\fBlistamsb\fP(1),
\fBprotbas\fP(1),
\fBrenumbas\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBunprotbas\fP(1),
\fBvxrefbas\fP(1),
\fBwhichbas\fP(1),
\fBxex1to2\fP(1),
\fBxexamine\fP(1),
\fBxexcat\fP(1),
\fBxexsplit\fP(1),
\fBxfd2atr\fP(1),
\fBxex\fP(5),
\fBatascii\fP(7),
\fBfauxtari\fP(7).
.sp
Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC  Reference
Manual\fP,  the  \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc.
.\" Generated by docutils manpage writer.
.