As
everyone should know, when an error occurs during the running of a BASIC
program, a code is returned to the user indicating the type of error that
has taken place. Unfortunately, you then have to look up the meaning of
these codes in a manual, and the explanations are all too often very brief
and written in a kind of Atarispeak which may be difficult if not
impossible to interpret. A better explanation of these codes might not
come amiss and I therefore present a guide to the meaning of ATARI Error
codes, why they occur and how to avoid them.
In this guide I give the error codes
followed by the 'official' name as found in the Atari BASIC Reference
Manual appendix B). Note that error names may vary between different
publications (even Atari publications!) as may the explanations given.
For further information, see the following
sources:
Atari
BASIC Reference Manual (Atari Inc.)
Technical Reference Notes (Atari Inc.)
DOS 3 Reference Manual (Atari Inc.)
Your Atari Computer (Osborne-McGraw Hill)
Revised
Mapping the Atari (Compute! Books)
Part 1 - Language specific errors.
Errors 2 - 21 only occur when a BASIC
program is running. Other languages (e.g. the Assembler-Editor cartridge)
also use these numbers, but have a completely different meaning. You
should also note that errors occurring during the execution from BASIC of
machine language subroutines may generate error codes which bear no
relation to the error which actually occurred.
Error-1
There is in fact no 'error' 1 in Atari
BASIC. The value is returned by the operating system on successful
completion of an input-output (I/O) operation. Quite properly, BASIC
doesn't bother telling you this, but just gets on with the job.
Error-2 Memory insufficient.
During the running of a program, BASIC
maintains a series of pointers in RAM to keep track of memory usage. Two
of these are MEMTOP (locations 741,742) and APPMHI (14,15). MEMTOP is a
pointer to the top of free memory. Above the
location found in MEMTOP is the display list, and following that the
screen RAM. The value in MEMTOP is moved up or down depending on the
graphics mode selected, the greater the memory requirement for any mode,
the lower is the value contained here. APPMHI is a pointer to the top of
your BASIC program. Whenever a new line is added to the program, or when
space is reserved for a string or array by the DIM statement, the value in
APPMHI is increased. If, either during the typing in of a program or
during a run, the value in APPMHI is greater than that in MEMTOP, error 2
is the result. (There is an exception - see error 147).
This error may also occur if RAMTOP (106),
the pointer to the top of available memory, is moved down
too far, since this will also cause MEMTOP to be lowered when the graphics
mode is changed. This could occur during repeated runs of a program which
deliberately lowers RAMTOP (e.g. during debugging). To avoid this, press
Reset before re-running such a program.
Error-3 Value error.
This is a common error which can be
surprisingly difficult to track down. It occurs when attempting to use a
number whose value is in some way unacceptable to the computer. Trying to
POKE a memory location with a negative number or one greater than 255 will
cause this problem. So too will trying to access part of a string or array
with a negative index value, or if the second index is smaller than the
first. For example, the following lines would generate this error:
10
DIM A$(9):? A$(7,1)
20
END
On the face of it this should be easily
avoidable. However, frequently a program first computes the value of a
variable then uses the variable in a POKE statement or as a string or
array index. It is all too easy during the initial computation to obtain a
value that is not acceptable to the machine. If the cause of this error is
not clear, check the actual value of your variables against what you think
they should be.
Error-4 Too many variables.
Atari BASIC only allows you the use of 128
different variable names. In practice, this should be enough for most
applications, so that you are unlikely to see this error. One point to
beware of is that variables used during program development, but not in
the final version, will remain in BASIC's variable name table even if no
longer used in the program. If you are running short of variables, you can
clear out the unwanted ones by LISTing your program to cassette or disk,
typing NEW (which clears the variable name table) and ENTERing your
program again.
Why does this limitation exist? When a
BASIC program is present in memory (or SAVEd to cassette or disk) it is in
tokenised form rather than full ATASCII format. Each BASIC keyword is
stored as a one byte token, so that (for example) the word RESTORE is
stored as one byte rather than seven (one for each character). Variables
are also stored as tokens, so that no matter how long the variable name,
it still only takes up one byte each time it occurs in the program. One
byte can only contain 256 different numbers, the BASIC keywords are
allocated numbers 0-127 (though not all are used) leaving the numbers
128-255 for the variables - giving 128 different names.
Should you need more than 128 variables,
then you can store numeric variables as elements of an array. For example,
the statement DIM ARRAY(99) will set up an array of 100 elements. Each of
these elements can hold a different number, but the array still only takes
up one variable name.
Error-5 String length error.
Whenever you use a string, you must first
tell the machine how long you want the string to be, using the DIM
statement. BASIC then reserves a section of memory to contain the contents
of your string. The convention used is that the first character of the
string is given the index value 1 (i.e. PRINT A$(1,1) would print the
first character of A$). If you use zero as an index, then error 5 occurs.
Incidentally, note that just to be confusing, the first element of an
array is given an index of zero!
This error will also occur if you use an
index value greater than the dimensioned string length. If you need a
longer string, you will have to alter the original DIM statement. Once
again, it is easy to cause this error when using variables as string
indices. See also errors 3 and 9.
Error-6 Out of data error.
Whenever you use the READ statement, BASIC
obediently tries to read as many items of DATA as you have instructed.
Every time one piece of data is read, a pointer is updated to point to the
next piece. If BASIC finds that there is no more data in the program, but
it is still under orders to READ, then the run stops and error 6 is
returned (but see below). This error is usually caused by miscounting the
number of data items to be read (often by means of a FOR ... NEXT loop) or
by missing out one or more pieces of data. A slightly more obscure cause
is that the pointer is not moved during a GOSUB...RETURN loop. If your
subroutine reads data contained in lines which are part of the subroutine
itself, and control then returns to the main program, when you next try to
read data the pointer will be pointing to data lines following the
subroutine (if any). To avoid this, you should make appropriate use of the
RESTORE statement.
You can make use of this error in your
programs. If you have large amounts of data to read in, then rather than
count them all up, you simply set a TRAP to the line where the program is
to continue when all DATA is read. You then set up a simple loop which
forces BASIC to read data until there is none left, at which point error 6
occurs but is caught by the TRAP and the program then continues as normal.
Error-7 Number greater than 32767.
Theoretically this error means that you
have used a number greater than 32767 (hex $7FFF) where this is not
acceptable to the machine. In practice, the only reason I know for this
error is a line number larger than 32767 - and I'm not sure why this limit
exists. Does anyone else have any further information?
If you try to type in a line with a line
number of 32768 or more, you simply get a syntax error on pressing Return.
However, Atari BASIC allows you to use variables as line numbers in
statements such as GOTO, GOSUB etc. so look out for the possibility that
the variable is larger than the allowed limit.
Error-8 Input statement error.
When you issue an INPUT statement, BASIC
expects the program to enter an appropriate reply, (either via the
keyboard or from cassette or disk) which will either be a number or a
character string. While it is quite acceptable to enter numbers in
response to a string input request (the characters making up the number
are treated just like any other string) it is not acceptable to enter a
string when BASIC expects a number. This is because BASIC will try to
assign the number which is input to a variable (e.g. if you respond with
'450' to the statement 'INPUT A', the variable A gets the value 450). It
clearly can't do this with a string of characters, and so will generate
this error. Pressing Return without entering any number at all will also
cause the error.
You can prevent users crashing your
programs in this manner by setting a TRAP so that any input which
generates an error could print a message and a request to try again.
Error-9 Array or string DIM error.
There are three possible causes of this
error.
i) As mentioned above, in Atari BASIC you
must DIMension all strings or arrays before use. If this is not done, and
you try to use an undimensioned string or array, this error results.
ii) You may also only dimension a string or
array once per program run. A good practice would be to contain your
initialization code (including setting up strings and arrays in a separate
subroutine called only once at the start of the program. This will prevent
accidental redimension of your strings. Should you for some reason need to
redimension strings or arrays during a program you must use the CLR
statement to undimension them first.
iii) There is an absolute limitation of
dimension size of 32767 for strings, and 5460 for arrays. Exceeding this
limit will generate error 9. Different strings or arrays when combined may
however exceed this limit, providing you don't exceed available memory, in
which case you will get error 2. (The odd looking figure of 5460 for array
size comes about because DIMensioning an array to this size sets up the
array to hold 5461 elements. Since each element takes up six bytes, and
5461 x 6 = 32766, one more element would exceed the 32767 limit
Error-10 Argument stack overflow.
As BASIC processes a program line, if it
comes across an arithmetical expression it first
places the various arithmetical operators it finds on an 'operator stack'.
The order in which the operators go on the stack is of some importance,
since it determines the order in which BASIC carries them out. In some
cases the order depends on priority (multiplication has priority over
addition, for example), otherwise on the order they occurred in the
statement. This order can be specifically overridden by using parentheses.
The size of the stack is limited. If the number of operators or the number
of parentheses cause the stack size to be exceeded (stack overflow), error
10 is returned. If this occurs, you will have to simplify the offending
expression.
Error-11 Floating point
overflow/underflow error.
BASIC stores numbers in your program in a
'floating point' format, using six bytes every time a number occurs. (It
is clearly more economical of memory to assign a variable to a number if
you intend to use that number frequently, since this will only use one
byte every time it occurs.) By using this format, BASIC can utilise
numbers as large as 10 to the power 98, or as small as 1 divided by 10 to
power 99 (should be a good enough range for most purposes!). If you exceed
these limits, then BASIC can't handle it, and this error results. The
usual cause of this is inadvertently dividing a number by zero (the
theoretical result of which is infinity).
Error-12 Line not found.
Certain keywords in BASIC are followed by a
line number, e.g. GOTO, GOSUB, etc. When such a statement is processed,
BASIC attempts to find the indicated line. If it can't do so, then it
literally has nowhere to go, so the run stops and this error is
returned.
There is an interesting feature here to do
with the TRAP statement. If you set a trap to a nonexistent line number,
and an error occurs to spring the trap, then instead of error 12, as you
might expect, you get the error which sprung the trap in the first place.
You can use this to clear previously set traps which are no longer wanted,
by setting the trap to a line known not to exist).
Error-13 No matching FOR statement.
On processing a FOR statement, BASIC puts
16 bytes into an area of memory called the run-time stack. This is in RAM,
pointed to by locations 142 and 143, and is situated directly above the
string/array area (itself just above the main body of the program). The
first 12 bytes are the numerical limit the variable can reach then the
step increase or decrease (six bytes per number in floating-point format).
The remaining four bytes are the variable number as it occurs in the
variable name table, the line number where the FOR occurs, and the offset
into that line. When it reaches the corresponding NEXT, BASIC checks that
the variable limit is not yet reached, and then returns to the line
containing the FOR. Clearly, if BASIC finds a NEXT without a corresponding
FOR, there is nothing on the run-time stack to
indicate the point of return, and program execution must stop.
GOSUB statements also use the run-time
stack, placing four bytes on it. These are an identifier byte to indicate
a GOSUB, the line number to go back to on reaching the RETURN statement,
and the offset into that line. See the description of error 16.
This error also occurs if your FOR ... NEXT
loops have not been properly nested. If the variable in the NEXT statement
is not the same as that in the FOR entry on the stack, then the same
problem arises.
Error-14 Line too long error.
When you type in a line of code and press
Return, your line goes into BASIC's input buffer, 128 bytes located from
1408 to 1535 (580-5FF hex). BASIC then proceeds to tokenise the line (see
error 4 above for an explanation of tokenising) and puts the resulting
tokens into its output buffer, 256 bytes of RAM located above the value
contained in MEMLO (743, 744). If the length of the tokenised line exceeds
256 bytes during the tokenising process, error 14 occurs. It's not very
likely, but if it does happen you will have to shorten the line.
Error-15 GOSUB or FOR line deleted.
This is a strange error which I have never
actually seen m practice. You will remember (see error 13 above) that
GOSUB and FOR statements use the run-time stack to indicate the line to
which control should pass on reaching the RETURN or NEXT statement. This
error means that on reaching a RETURN (or NEXT) BASIC fetches a line
number from the run-time stack, but cannot then find that line. This in
turn implies that the line was deleted between BASIC's encountering the
GOSUB (or FOR) and the RETURN (or NEXT). It is difficult to think of
circumstances in which this might occur, but it is possible that POKEing
around in the area of RAM which contains the program might alter line
numbers. Another possibility is faulty RAM, causing program lines to be
lost.
Error-16 RETURN error.
This error is analogous to error 13 above.
On reaching a RETURN, BASIC gets the line number to return to (and the
offset into that line) from the run-time stack. If a RETURN is reached
before a GOSUB, there won't be an entry on the stack and program execution
will have to stop.
Error-17 Garbage error.
A very reassuring error message to get!
What it means is that while executing the program, BASIC has come across a
line which contains non-executable (garbage) code. There are several
possible reasons. Although Atari BASIC performs syntax checking on entry
of program lines, it is quite easy (especially if you are in a hurry) to
miss the syntax error display you normally get. This erroneous line will
however be entered into memory (at least in part), and when BASIC finds it
again error 17 is the result. It is also likely that POKEing directly into
the RAM containing your program would alter the code, causing havoc at run
time. The third possibility (least likely of all) is that your RAM might
be at fault.
Error-18 Invalid string character.
This error relates to the use of the VAL
function. Although numbers are usually held as constants or as numeric
variables, it is possible to store numbers as strings. To convert a number
to a string, you use the STR$ function. You can then perform string
handling operations on the result. To convert the string back into a
number for arithmetical operations, VAL is used. VAL can only be used
however if the string is composed of numbers, or (at the least) if the
first character of the string is a number. If this condition is not met,
this error is generated.
Error-19 LOAD program too long.
This error is a very simple, one: it means
that the program you are trying to LOAD is too large to fit into the
available RAM. This is not likely-to be seen with today's 48K-plus
machines, but it must have been fairly common in the days of the 8K
Ataris. There is no easy solution; if this happens, you will have to
install some more memory in your computer. It is possible that this error
might occur in a 48K machine with faulty RAM.
Error-20 Device number error.
This error occurs during input/output
operations if you try to use an incorrect IOCB (channel) number. (See
error 134 in the second part of this article for a brief explanation of
IOCBs.) The Atari can use up to eight IOCBs (numbered 0-7) for
communication with peripherals, but BASIC reserves IOCB zero for its own
use. The IOCB number is the number following the 'hash' sign in statements
such as PRINT #6, OPEN #1, CLOSE #7, etc. and must be numbered from one to
seven inclusive. See also error 134.
Error-21 LOAD file error.
When you try to LOAD (or CLOAD) a program,
the computer expects to receive a BASIC program in tokenised format (see
error 4 for an explanation of tokenising). Tokenised BASIC programs are
only stored on cassette or disk with the SAVE (or CSAVE) command, and
files created by any other means will not be in this form. Trying to LOAD
anything other than a tokenised BASIC program will produce error 21.
Examples of such files would include any file LISTed to cassette or disk
(full ATASCII format), machine language programs, screen memory dumps etc.
If this error occurs, you will have to use
the correct command to reload your file. For example, this would be ENTER
for LISTed files, the DOS binary load option L for machine code files, and
so on.
Next issue - Steve Pedler concludes this
article with a comprehensive look at the Error codes associated with
INPUT/OUTPUT and the Operating System.
top
