======== listamsb ======== ------------------------------------------------------------ List the source of a tokenized Atari Microsoft BASIC program ------------------------------------------------------------ .. include:: manhdr.rst SYNOPSIS ======== listamsb [**-a**\] [**-v**\] [**-h**\] [**-i**\] [**-u**\] [**-t**\] [**-m**\] [**-s**\] [**input-file**\] DESCRIPTION =========== **listamsb** acts like the *LIST* command in Atari Microsoft BASIC. It reads a tokenized (SAVEd) AMSB program and prints the code in human-readable format. By default, output is piped to **a8cat**\(1), which converts the ATASCII output to something that's human-readable on modern terminals. This means **a8cat** must be available somewhere in **$PATH**\. **listamsb** supports both versions of Atari Microsoft BASIC: the disk-based version 1 and the cartridge-based version 2. The language is the same for both versions, so there's no need to specify it. **input-file** must be a tokenized AMSB program. If no **input-file** is given, input is read from stdin. Output is to stdout. Use shell redirection to save the output to a file. OPTIONS ======= **-a** Output raw ATASCII. This option must be used with a pipe or redirection, as **listamsb** will not write ATASCII to a terminal. **a8cat** is not used, with this option. **-c** Check only. No output on stdout. Diagnostics are still printed on stderr, and the exit status is unchanged. **-r** *line-range* Show only part of the listing. *line-range* can be a single line, or a comma-separated pair of starting and ending line numbers (e.g. **100,200**). If the start line number is omitted (e.g. **,100**), it will be treated as **0** (meaning, list from the beginning of the program). If the ending line number is omitted (e.g. **100,**), it means "list until the end of the program". **-r,** is equivalent to not using the **-r** option at all. **-v** Verbose output, on stderr. **-h**\, **--help** Print built-in help and exit. **--version** Print version number and exit. **-i**\, **-u**\, **-t**\, **-m**\, **-s** These options are passed to **a8cat**. See its man page for details. If the **-a** or **-c** option is used, these options have no effect. DIAGNOSTICS =========== All error and warning messages are written to the standard error output. Fatal errors ------------ These are errors in the program header at the start of the file. They generally mean the input isn't actually an tokenized Atari Microsoft BASIC file. - not an AMSB file: first byte not $00 Pretty self-explanatory: if the file doesn't begin with a *$00* byte, it's not a tokenized AMSB file. - not an AMSB file: too big (*N* bytes), won't fit in Atari memory The file can't be a tokenized AMSB file because there was no way for it to be created. It must be some other kind of file that begins with a *$00* byte. - not an AMSB file: program size too small (*N*). Atari BASIC file? The program header claims the file is 0, 1, 3, or 4 bytes long. This is impossible, so this isn't an AMSB file. A lot of Atari BASIC programs begin with three *$00* bytes, so that might be what this is. - program length is 2, no code in file (SAVE after NEW) Probably, someone did a SAVE when there was no program in memory. It could also mean this isn't an AMSB file at all. Warnings -------- These are non-fatal: **listamsb** logs the warning to stderr, then continues processing. - unexpected EOF, file truncated? A tokenized AMSB file always ends with three null bytes (*$00*\). This file doesn't. Probably the rest of the file is missing. - line *L*: EOL address *A* too (low|high) Each line begins with the address of the next line. If the address is below *$0700*, it's below the minimum value of *MEMLO*, which is impossible. If it's above *$bc1f*, it would be in the display list, screen memory, or OS ROM (also impossible). File is corrupt, or not an AMSB file. - line *L*: EOL address *A* <= previous *B* Corrupt file, or not an AMSB file. - line *L* EOL address doesn't match actual line length *N* Same as above: corrupt, or not AMSB. - line number out of order Probably means the file is corrupted, or isn't really an AMSB file. - line number out range The program contains a line number that's greater than *63999*. How did that happen? - line *L* has character *C* outside of a string. maybe Atari BASIC? This happens when ATASCII codes 0 to 31 (*$1f*\) appear in the program. AMSB can create files like this, but at runtime, it's a syntax error. More likely, it means this is an Atari BASIC file. - actual program size doesn't match program size in header Might mean this isn't an AMSB file. If you're sure it is, part of the file might have been overwritten with *$00* bytes. - trailing garbage at end of file Might mean this isn't an AMSB file. If you're sure it is, garbage data has somehow gotten appended to the file, after the three *$00* bytes that end the program. Maybe it was downloaded with a crappy version of XMODEM that pads the last block. - file has *N* unknown tokens Either the file is corrupt, or this is a file from some *other* variant of Microsoft BASIC (e.g. Commodore, AppleSoft, GW-BASIC, TRS-80). If you see this warning, you'll also see *N* messages in the actual listing. LIMITATIONS =========== Unlike **listbas**, there's no color syntax highlighting. Probably there never will be. It's hard to reliably detect AMSB files. Most of the time, it can at least detect Atari BASIC files, but occasionally you'll get gibberish output instead. EXIT STATUS =========== 0 for success, 1 if there was an error reading the input (e.g. file not found), or 2 if the input file had errors or warnings (see **DIAGNOSTICS**). .. include:: manftr.rst