LISTAMSB(1)

NAME
listamsb - List the source of a tokenized Atari Microsoft BASIC program

SYNOPSIS

listamsb [-l] | [-C] | [-D] | [[-a] [-c] [-v] [-h] [-i] [-u] [-t] [-m] [-n] [-s] ...] [-r line-range] [input-file] [output-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.

Programs created with SAVE "filename" LOCK are autodetected, and will be listed normally. It's also possible to convert a LOCKed program to an unencrypted one, with the -l option.

Programs can be "crunched" and "decrunched" with the -C and -D options.

If no output-file is given, output is to stdout.

OPTIONS

-a  Output raw ATASCII. This option must be used with an output-file, a pipe, or redirection: 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. It's an error to give an output-file with this option.

-C  "Crunch" program: remove comments and spaces that occur outside of a string. The resulting program is usually 5 to 10 percent smaller, and will RUN correctly, but will be difficult to edit in AMSB because its parser requires the spaces. Also, if any comment-only lines are the target of GOTO or GOSUB, the program won't run because all comment-only lines are removed.

    This option must be used with an output-file, since seeking is done. None of the other options have any effect with -C.

-D  "Decrunch" a crunched program. Puts spaces where they're required for AMSB's parser. The result will be editable in AMSB. Of course, any comments that were removed during crunching will not magically be retored (they're gone).

    This option must be used with an output-file, since seeking is done. None of the other options have any effect with -D.

-r line-range
    Show only part of the listing. line-range can be a single line, or a comma- or hyphen-separated pair of starting and ending line numbers (e.g. 100,200, or 1000-2000).

    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, or -r- is equivalent to not using the -r option at all.

-l  "Lock" or "unlock" the program. Locked programs are created with SAVE "filename" LOCK. The "encryption" is a reciprocal cipher: locking and unlocking are the same operation (similar to ROT13). The output will be the locked or unlocked tokenized program (rather than a listing).

    This option must be used with an output-file, a pipe, or redirection: listamsb will not write tokenized BASIC to a terminal. a8cat is not used, with this option. None of the other options have any effect with -l.

-n  No empty line. By default, listamsb prints an empty line at the start of the output, to match AMSB's LIST command.

-v  Verbose output, on stderr. May be given twice for extra verbosity, which shows each line number, its offset, length, and end-of-line pointer.

-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 any of the -a, -c, or -l options are 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 or $01

    Pretty self-explanatory: if the file doesn't begin with a $00 or $01 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 is suspiciously long

    The line is >128 bytes long, but less than 256. AMSB can execute lines of this length, but it's impossible to actually enter them in the editor, because a logical line can't be longer than 3 screen lines. Possibly corrupted file.

•   line L is impossibly long

    The line is >= 256 bytes long. AMSB will crash, if you try to LOAD the file. Corrupted file.

•   line L EOL address doesn't match actual line length N

    Corrupt file, or not an AMSB file.

•   line number out of order

    Corrupt file, or not 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.

•   program size doesn't match size in header

    Might mean this isn't an AMSB file. If you're sure it is, it might be truncated, or part of the file might have been overwritten with $00 bytes. It could also mean the length in the header has somehow gotten corrupted.

•   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. The good news is, AMSB will just ignore the garbage when you LOAD the file, so it won't hurt anything.

•   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 <unknown token XX> messages in the actual listing.

ENVIRONMENT

A8CAT The path to the a8cat(1) binary. Can be a full path or just the executable name, in which case it will be searched for with the normal PATH mechanism. If not set, a8cat is used. If there are spaces or other metacharacters, they must be escaped.

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).

COPYRIGHT

WTFPL. See http://www.wtfpl.net/txt/copying/ for details.

AUTHOR

B.  Watson <urchlay@slackware.uk>; Urchlay on irc.libera.chat ##atari.

SEE ALSO

a8cat(1), a8eol(1), a8xd(1), atr2xfd(1), atrsize(1), axe(1), bas2aplus(1), blob2c(1), blob2xex(1), cart2xex(1), cxrefbas(1), dasm2atasm(1), diffbas(1), dumpbas(1), f2toxex(1), fenders(1), listbas(1), listamsb(1), protbas(1), renumbas(1), rom2cart(1), unmac65(1), unprotbas(1), vxrefbas(1), whichbas(1), xex1to2(1), xexamine(1), xexcat(1), xexsplit(1), xfd2atr(1), xex(5), atascii(7), fauxtari(7).

Any good Atari 8-bit book: De Re Atari, The Atari BASIC Reference Manual, the OS Users' Guide, Mapping the Atari, etc.