diff options
Diffstat (limited to 'ossintbas.7')
| -rw-r--r-- | ossintbas.7 | 582 |
1 files changed, 582 insertions, 0 deletions
diff --git a/ossintbas.7 b/ossintbas.7 new file mode 100644 index 0000000..dda00d3 --- /dev/null +++ b/ossintbas.7 @@ -0,0 +1,582 @@ +.\" 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 +\fI\%https://forums.atariage.com/topic/257029\-oss\-d\-day\-part\-3\-integer\-basic\-source\-code\-now\-in\-pd/\fP +.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\&. +.sp +Abbreviation: \fBVI.\fP +.UNINDENT +.UNINDENT +.sp +\fBVDEC\fP \fI<var>\fP +.INDENT 0.0 +.INDENT 3.5 +Decrement (subtract 1 from) a variable. Faster than \fBA=A\-1\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 PERFORMANCE +.sp +OSS Integer BASIC is \fIfast\fP, compared to other interpreted BASICs on +the Atari. It even outperforms Turbo BASIC XL (though, not \fIcompiled\fP +Turbo). +.sp +For testing, I used a modified version of the Sieve of Eratosthenes +program, found in the source for \fBbas55\fP\&. The program finds and +prints all the prime numbers between 2 and 1000. The code: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +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) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +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\(aqs OS floating +point replacement ROM. For Integer BASIC, BASIC XL and BASIC XE, +separate runs were done with the line \fB5 FAST\fP at the start of the +program. Results: +.TS +center; +|l|l|l|. +_ +T{ +BASIC +T} T{ +Jiffies +T} T{ +Speedup +T} +_ +T{ +Atari 8K +T} T{ +1867 +T} T{ +\-\- +T} +_ +T{ +A+ +T} T{ +1671 +T} T{ +1.12 +T} +_ +T{ +Atari 8K (Fastchip) +T} T{ +1587 +T} T{ +1.18 +T} +_ +T{ +A+ (Fastchip) +T} T{ +1569 +T} T{ +1.19 +T} +_ +T{ +XE +T} T{ +1440 +T} T{ +1.3 +T} +_ +T{ +AMSB2 +T} T{ +1518 +T} T{ +1.23 +T} +_ +T{ +XL +T} T{ +1270 +T} T{ +1.47 +T} +_ +T{ +Altirra +T} T{ +1166 +T} T{ +1.67 +T} +_ +T{ +XL (FAST) +T} T{ +1110 +T} T{ +1.68 +T} +_ +T{ +XL (Fastchip) +T} T{ +1049 +T} T{ +1.78 +T} +_ +T{ +XL (Fastchip, FAST) +T} T{ +887 +T} T{ +2.1 +T} +_ +T{ +Turbo +T} T{ +825 +T} T{ +2.3 +T} +_ +T{ +XE (FAST) +T} T{ +777 +T} T{ +2.4 +T} +_ +T{ +XE (Fastchip, FAST) +T} T{ +777 +T} T{ +2.4 +T} +_ +T{ +Altirra (Fastchip) +T} T{ +769 +T} T{ +2.43 +T} +_ +T{ +Integer +T} T{ +719 +T} T{ +2.6 +T} +_ +T{ +Integer (FAST) +T} T{ +575 +T} T{ +3.25 +T} +_ +.TE +.sp +Turbo BASIC XL, Atari Microsoft BASIC, and OSS Integer BASIC run at +the same speed with or without the Fastchip ROM, since they don\(aqt use +the OS floating point routines. +.sp +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. +.sp +If you get rid of lines 180 to 210 (don\(aqt 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). +.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. +. |