diff options
Diffstat (limited to 'amsb.7')
| -rw-r--r-- | amsb.7 | 600 |
1 files changed, 600 insertions, 0 deletions
@@ -0,0 +1,600 @@ +.\" 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 "AMSB" 7 "2025-03-13" "0.2.2" "Urchlay's Atari 8-bit Tools" +.SH NAME +amsb \- Atari Microsoft BASIC Notes +.SH DESCRIPTION +.sp +AMSB is actually a pretty cool BASIC for the Atari 8\-bit. I never +got the chance to use it \(aqback in the day\(aq because it was expensive, +required a floppy drive and at least 32K of RAM (my poor 400 had a +tape drive for the first few years), and then later on, there was +Turbo BASIC XL, which was cooler than AMSB, and also freeware. +.sp +This file is a collection of notes I made to myself while developing +listamsb. The information here might be useful (e.g. if you\(aqre trying +to repair a damaged AMSB file) and hopefully is interesting. Enjoy! +.sp +This file is part of the bw\-atari8\-utils source. You can get the +latest version of the source from: +.sp +\fI\%https://slackware.uk/~urchlay/repos/bw\-atari8\-tools\fP +.sp +\&...which you can either view with a web browser or use with the \(aqgit +clone\(aq command. +.SH NOTES +.SS Tokenized file format +.sp +File begins with a 3\-byte header: +.TS +center; +|l|l|. +_ +T{ +Offset +T} T{ +Purpose +T} +_ +T{ +0 +T} T{ +0 for a normal program, 1 for LOCKed (encrypted) +T} +_ +T{ +1 +T} T{ +LSB, program length, not counting the 3\-byte header +T} +_ +T{ +2 +T} T{ +MSB, program length +T} +_ +.TE +.sp +The program length should always be the actual file size minus 3. If +it\(aqs not, the file has either been truncated or had junk added to the +end. In a LOCKed program, the program length bytes are not encrypted. +.sp +After the header, the lines of code (encrypted, for LOCKed programs). +Each line has a 4\-byte header: +.TS +center; +|l|l|. +_ +T{ +0 +T} T{ +LSB, address of the last byte of this line... +T} +_ +T{ +1 +T} T{ +MSB, address ...which is ignored on LOAD! +T} +_ +T{ +2 +T} T{ +LSB, line number +T} +_ +T{ +3 +T} T{ +MSB, line number +T} +_ +.TE +.sp +The rest of the line is the tokens, terminated by a $00 byte. The +next 2 bytes after the $00 is the last\-byte offset of the next line. +.sp +The last "line" of the program has a $0000 offset, which indicates the +end of the program. Since the actual last line ends with a $00, that +means there will be three $00 bytes in a row as the last 3 bytes of +the file. And that\(aqs the \fIonly\fP place 3 $00\(aqs in a row will occur. +.sp +Tokenization is "lightweight": there are no tokenized numerics, +they\(aqre just stored as ASCII characters, as typed. There\(aqs no "string +constant follows" token like there is in Atari BASIC (well, there is, +it\(aqs just a double\-quote, $22. There\(aqs no length byte). Variable names +are not tokenized, either, they\(aqre just stored as\-is (name in ASCII, +including trailing $ for strings, etc). Numeric constants are just +stored as ASCII digits, just as you typed them. +.sp +In fact the only things that are tokenized are BASIC keywords: +commands and functions... NOT including user functions defined +with DEF (those are stored as just the ASCII function name, like +variables). +.sp +There are 2 sets of tokens. One set is single\-byte, $80 and up. +These are commands. The other set is functions, which are 2 bytes: +$FF followed by the token number. See amsbtok.h in the source for the +actual tokens. +.sp +AMSB saves the end\-of\-line pointers, but it totally ignores them +on LOAD. The SAVEd file format does \fInot\fP have a load address (as e.g. +Commodore BASIC does), so there\(aqs no way to know the address of the +start of the program (other than counting backwards from the next line, +since its address is known). It\(aqs not just a constant either: it +depends on what MEMLO was set to when the program was saved (which varies +depending on what version of AMSB you have, what DOS you boot, whether +or not you have the R: device driver loaded, etc etc). +.SS Redundant Tokens +.sp +There are two separate tokens each for PRINT and AT: +.TS +center; +|l|l|. +_ +T{ +$ab +T} T{ +PRINT +T} +_ +T{ +$ac +T} T{ +PRINT +T} +_ +T{ +$df +T} T{ +AT( +T} +_ +T{ +$e0 +T} T{ +AT +T} +_ +.TE +.sp +When tokenizing a line, AMSB will actually use the $ab token if +there\(aqs a space after PRINT (or ?), otherwise it will use the +$ac token. These lines actually get tokenized differently: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10 PRINT "HELLO" +10 PRINT"HELLO" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Same applies to the $df and $e0 AT tokens: if the user entered +"AT(X,Y)", $df is used. Otherwise, with "AT (X,Y)", $e0 is used +(followed by an ASCII left parenthesis). +.sp +3 tokens include the opening parenthesis: +.TS +center; +|l|l|. +_ +T{ +$d2 +T} T{ +TAB( +T} +_ +T{ +$d6 +T} T{ +SPC( +T} +_ +T{ +$df +T} T{ +AT( +T} +_ +.TE +.sp +Normally in AMSB, it\(aqs OK to leave a space between a function name +and the left\-paren. PEEK (123) and SIN (1) are both valid. However, +for SPC and TAB, no space is allowed, because the ( is part of the +token. AT would be the same way, except there\(aqs a separate token $e0 +that \fIincludes\fP the space. Weird, huh? A side effect of this is +that "SPC (10)" or "TAB (10)" won\(aqt be treated as a function call. +Instead, the SPC or TAB is treated as a variable name. If you write: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +PRINT TAB (10);"HELLO" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\&...it\(aqll print " 0 HELLO" at the start of the line[*], instead of "HELLO" +in the 10th column as you might have expected. It also means that AT, +TAB, and SPC are valid variable names in AMSB, which is an exception +to the rule that keywords can\(aqt be used as variable names (e.g. SIN=1 +or STRING$="HELLO" are invalid). +.sp +[*] Unless you\(aqve assigned another value to TAB, of couse. +.SS Unused Tokens +.sp +If you look at the token list in amsbtok.h (or in a hex dump +of the AMSB executable or cartridge image), you\(aqll see a lot of +double\-quotes mixed in with the list. AMSB doesn\(aqt actually tokenize +the " character (it\(aqs stored as $22, its ASCII value), so these seem +to be placeholders, either because some tokens were deleted from the +language during its development, or else they\(aqre intended for some +future version of AMSB that never happened. +.sp +The weird quote tokens are $99, $c8 to $d0, $d5, and $e7 to $ed. If +you hexedit a program to replace a regular double\-quote with one of +these tokens, it will list as either "" or just one ", but it will +cause a syntax error at runtime. +.SS LOADing Untokenized Files +.sp +If the first byte of the file is anything other than $00 or $01, +AMSB\(aqs LOAD command reads it in as a text file (LISTed rather than +SAVEd). +.sp +When LOAD is reading a text file, if the last byte of the file isn\(aqt +an ATASCII EOL ($9b), you\(aqll get #136 ERROR. The program doesn\(aqt get +deleted, but the last line of the file didn\(aqt get loaded. This could +happen if a LISTed file somehow got truncated. +.sp +While on the subject... the manual doesn\(aqt mention it, but if you LOAD +a text file without line numbers, the code gets executed in direct +mode during the load (like Atari BASIC\(aqs ENTER command does). This +means you could write scripts (batch files) for AMSB... though you\(aqd +be better off using MERGE, rather than LOAD (MERGE is basically the +same thing as Atari BASIC\(aqs ENTER). +.SS Program Length Header Mismatch +.sp +When AMSB\(aqs LOAD command executes, it reads the 3\-byte header, then +reads as many bytes as the header\(aqs program length says. +.sp +If the header length is longer than the rest of the file, you get +a #136 ERROR (aka Atari\(aqs EOF), and the partially loaded program is +erased (basically it does a NEW). +.sp +If the length is shorter than the program, it\(aqll stop loading no +matter how much more data is in the file. This means it can stop in +the middle of a line. It also means, if there was already a program in +memory that was longer than the program length, you get a "hybrid" mix +of the new program followed by the remainder of the old one. This is +because the three $00 bytes at the end of the program weren\(aqt read in. +.sp +If the program length is correct for the actual program (so the three +$00 bytes get read), but there\(aqs extra data appended to the file, AMSB +will never read the extra data at all. +.SS String Limitations +.sp +String literals in AMSB cannot contain the | or ATASCII heart +characters. +.sp +AMSB uses | as a terminator for quoted strings, e.g. "STRING" will +be tokenized as: "STRING| +.sp +If you try to use a | in a quoted string, it gets turned into a double +quote: "FOO|BAR" comes out as "FOO"BAR which is a syntax error! +.sp +String variables can store | but only with e.g. CHR$(124) or reading +from a file: it\(aqs string \fIliterals\fP that don\(aqt allow it. +.sp +The reason | is used for a terminating quote is to allow doubling up +the quotes to embed them in a string: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +A$ = "HAS ""QUOTES""" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +PRINT A$ will print: HAS "QUOTES" +.sp +At first I thought "no pipe characters in strings, WTF man?" but it\(aqs +probably no worse than Atari BASIC\(aqs "no quotes in strings constants" +rule. It \fIwould\fP be nice if the AMSB manual actually documented the +fact that | can\(aqt occur in a string constant. Not documenting it makes +it a bug... and they have unused tokens in the $Fx range, I don\(aqt see +why they had to use a printing character for this. +.sp +You also can\(aqt put a heart (ATASCII character 0) in a string +literal. It will be treated as the end of the line, as though you +pressed Enter (and anything else on the line is ignored). This isn\(aqt +documented in the manual, either. +.sp +Like the | character, you can use CHR$(0) to store a heart in a string +and it will work correctly. +.SS Line Number Range +.sp +AMSB doesn\(aqt allow entering line numbers above 63999, but if a file +is e.g. hex\-edited to have a line number that\(aqs out of range, it will +LIST and RUN just fine... except that it\(aqs impossible to GOTO or GOSUB +to an out\-of\-range line. It will still execute if program flow falls +into it. +.SS Differences Between Versions +.sp +The language is the same in AMSB versions 1 and 2. Tokenized files +made by one version will LOAD and RUN in the other version. +.sp +Version 1, the disk version, always has the full set of commands +avaiable. Version 2, the cart, only has the full set if the extension +disk is booted. The missing ones still get tokenized, but you get SN +ERROR at runtime if you try to execute them. This doesn\(aqt affect the +detokenizer at all. The missing commands: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +AUTO +DEF (string version only) +NOTE +RENUM +TRON +TROFF +DEL +USING +STRING$ (function) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +RENUM only works in direct mode, not a program. Executing it +gives a FUNCTION CALL ERROR. +.sp +AUTO is (oddly) allowed in a program. Executing it exits the program +and puts you back in the editor, in auto\-numbering mode. +.sp +It would seem weird to have POINT available but not NOTE... except +that AMSB doesn\(aqt even \fIhave\fP POINT. Instead, the disk addresses +returned by NOTE are used with AT() in a PRINT statement. Not sure +if AT() works without the extensions loaded, but it won\(aqt be useful +anyway without NOTE. +.sp +One other difference between versions 1 and 2: version 2 will LOAD and +RUN the file D:AUTORUN.AMB at startup, if it exists. +.SS Colon Weirdness +.sp +AMSB allows comments to be started with the ! and \(aq characters (as +well as the traditional REM). For the ! and \(aq variety, if they +come at the end of a line after some code, you don\(aqt have to put a colon. +Example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10 GRAPHICS 2+16 ! NO TEXT +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +However... in the tokenized format, there \fIis\fP a tokenized colon +just before the tokenized ! or \(aq character. LIST doesn\(aqt display it. +If you did put a colon: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10 CLOSE #1:! WE\(aqRE DONE +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\&...then there will be \fItwo\fP colons in the tokenized file, and only +one will be LISTed. +.sp +The ELSE keyword works the same way. In this line: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10 IF A THEN PRINT ELSE STOP +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\&...there is actually a : character just before the token for ELSE. +.sp +Even weirder: you can put as many colons in a row as you like, and +AMSB will treat it like single colon. This line of code is valid +and runs correctly: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +10 PRINT "A"::::::PRINT "A" +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +These colons are displayed normally in LIST output. +.SS Memory Usage +.sp +On a 48K/64K Atari, FRE(0) for AMSB 1 with DOS booted (since you can\(aqt +use it without) but no device drivers is 21020. MEMLO is awfully high +($6a00). +.sp +For AMSB 2 with DOS booted, but without the extensions loaded, FRE(0) +is 24352. With extensions it\(aqs 20642 (even though the banner says 20644 +BYTES FREE). +.sp +AMSB 2 without DOS gives you 29980, but how are you gonna load or save +programs without DOS? Nobody wants to use cassette, especially not +people who could afford to buy the AMSB II cartridge. +.SS LOCKed Programs +.sp +If you save a program with SAVE "filename" LOCK, it gets saved in an +"encrypted" form. Loading a locked program disables the LISTing or +editing the program (you get LK ERROR if you try). +.sp +The "encryption" is no better than ROT13. To encrypt, subtract each +byte from 0x54 (in an 8\-bit register, using twos complement). To +decrypt, do the same. This is a reciprocal cipher, and you can think +of it as the binary equivalent of ROT13. +.sp +You can tell a LOCKed program because its first byte will be 1 instead +of 0. The next 2 bytes (the program length) unencrypted. The rest of +the file is encrypted with the lame scheme described above. +.sp +When AMSB has a LOCKed program loaded into memory, it\(aqs \fInot\fP stored +encrypted in RAM. It would be perfectly possible to write BASIC code +using direct mode to write the tokenized program out to disk. The +program starts at MEMLO and extends up to the first occurrence of +three $00 bytes. The hardest part of this would be generating the +header using only direct\-mode BASIC statements (but it could be done). +.sp +However... there\(aqs no need to do that. AMSB has a flag that tells it +whether or not the currently\-loaded program is LOCKed. You can just +clear the flag: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +POKE 168,0 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Now AMSB won\(aqt consider the program LOCKed, and you can SAVE a regular +copy of it (and LIST, edit, etc). +.SS Line Length Limit +.sp +In the editor, after a POKE 82,0 (to set the left margin to 0), you +can enter 120 characters (3 screen lines) on a logical line. If you +enter a program line that way \fIwithout\fP a space after the line number, +then LIST it, it will be 121 characters long, because AMSB will +display a space after the line number. +.sp +If you use a text editor (or write a program) to create an untokenized +BASIC program, you can have a line of code that\(aqs 125 characters +long. AMSB will accept it just fine, with LOAD. If a line is 126 +characters or longer, AMSB will silently ignore that line when +LOADing. +.sp +If you create a 125\-character line (with a text editor) consisting +only of a comment that begins with ! or \(aq, without a space after the +line number, LOAD it, then SAVE it, that line will be 129 bytes long +in tokenized form. AMSB will LOAD it with no problems. +.sp +If you hex\-edit a SAVEd file to create a longer line, AMSB will +accept that, too... up to 255 bytes. At 256 bytes, AMSB will lock +up after LOAD. +.SS Crunching +.sp +AMSB stores spaces in the tokenized program, just like other 8\-bit +MS BASICs do, but it requires you to put spaces between keywords and +variables (unlike e.g. Commodore 64 BASIC). This seems to be because +AMSB allows keywords inside of variable names: you can have a variable +called LIFE (which contains the keyword IF) in AMSB, but you can\(aqt in +C=64 BASIC (which gives a syntax error becase it sees "L IF E"). +.sp +This applies to numbers, too: POKE710,0 is a syntax error in +AMSB. This is because POKE710 is actually a valid variable name: try +POKE710=123 followed by PRINT POKE710. +.sp +However. The spaces aren\(aqt needed when the program is RUN. It would be +possible to remove all the spaces outside of strings or comments and +the program would still work fine. +.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. +. |