1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
========
listamsb
========
------------------------------------------------------------
List the source of a tokenized Atari Microsoft BASIC program
------------------------------------------------------------
.. include:: manhdr.rst
SYNOPSIS
========
listamsb [**-l**] | [[**-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.
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.
**-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).
Output raw ATASCII. 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
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 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.
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
|
