Oh, Those ?#$%!
by Steve Hardin
Scenario: It's two o'clock in the morning. You have just finished keying in a program listing from Hi-Res into your favorite computing machine, and it's time to see what you've created. You type RUN, and sit back, expecting to see a spectacular graphic display. What do you get? ERROR 17 AT LINE 1220.
What in blue blazes!! What is ERROR 17?! Muttering mightily under your breath, you reach for your copy of the Atari Basic Reference Manual. Ah, here it is, listed on the inside of the front cover: ERROR CODE 17 ... Garbage Error. Garbage Error!! What does that mean?!
Ah . . . down here at the bottom it says, "For explanation of Error Messages see Appendix B." OK . . . Appendix B. Here it is. Wait a minute, what does this mean? "Bad RAM Bits?! Type NEW or power down, and reenter the program?!" You've spent six hours entering this program! Who do they think they're kidding?!
All is not lost. It is the intent of this series to give you a better understanding of those cryptic numbers Atari calls error codes that are generated by Basic, the Atari Disk Drive, the Atari Program Recorder, and, to some extent, the Atari 850 Interface Module. We will explain what each error code means, how to avoid error, and how you can use them to your advantage. (Error codes that occur when using assembly language, we'll leave to our assembly language experts.)
There are two different types of errors: errors in the Basic program, and errors that are generated from a peripheral device. In some instances, the device will notify the computer that an error has occurred. Otherwise it's the computer that generates the error. For our uses, it doesn't matter. We are just looking at the error code itself.
The Basic Trap Statement
Use error codes in programming? That's right. Most of the errors generated by your Atari Home Computer can be trapped and checked, and then used by your program.
Atari, in their wisdom, included in their Basic, a statement called Trap. This statement, added to any program line, will watch for any errors following the Trap statement. If an error occurs, the Trap will branch the program to another line (which you have designated in the Trap statement). There you can check the error and branch to any other program line that you want. (We'll discuss how to check the error in a minute).
Try this little experiment. Insert the Basic cartridge into your computer, turn the power off and then turn the power back on again. Key in the following program and then run it.
10 TRAP 60
20 OPEN # 1,4,0"D:JUNK"
30 GOTO 90
60 PRINT "ERROR"
90 PRINT "END OF PROGRAM"
NOTE: This program will work, even if you do not have a disk drive.
The Trap is set in line 10. Line 20 calls for the opening of a file on disk drive 1. If you have no disk drive in your system, or if the file does not exist, then the drive generates an error. Because of the Trap, the program branches to line 60 and prints the statement, ERROR. Once the error "springs" the Trap, it will have to be reset.
Then line 90 prints, END OF PROGRAM.
Suppose you have a disk drive and your disk contains a file called junk. In that case, the Trap will never be sprung. File junk will be opened (line 20), and the program will jump to line 90 (line 30). If the program contained more statements, then the Trap remains set until an error occurs.
Oddly enough, if you wish to remove the Trap, you also use the Trap statement. Adding, TRAP 32768 will clear your original Trap statement. For more details on Trap see the Atari Basic Reference Manual.
Checking the Error
Remove line 10 from the program and run it. Without the Trap an error message will appear on your television screen. The exact Error Code number will depend on your computer configuration, but in any event, the error will have occurred at line 20. Remember this number.
Type the following: 60 PRINT "ERROR"; PEEK(195) and run the program. It will ERROR XXX. XXX is the same number that was generated when you ran the program with line 10 deleted! How come? When an error happens, the computer stores the value of the Error Code into decimal location 195. You can PEEK at that location and read that value at any time.
Depending on what you want your program to do, you can now make decisions based on the Error Code generated. Let's make a few changes in our program:
60 X = PEEK(195)
70 PRINT "ERROR";X
80 IF X = 138 THEN PRINT "NO DISK DRIVE"
85 IF X = 170 THEN PRINT "NO SUCH FILE"
Now run the program and see what happens. You have just used an Error Code in a program.
The Error Codes
Let's take a look at some of the Error Codes. As you read you may want a few references. The Atari Disk Operating System II Reference Manual and the Atari Basic Reference Manual are helpful. The Atari 850 Interface Module Technical Manual is also handy, particularly if you plan to program the interface module ports.
Another excellent source is De Re Atari. Anyone who is planning to do some serious programming on the Atari Home Computer should have a copy of this excellent reference in his library. Written by several of the Atari programming wizards, the book is available from the Atari Programming Exchange (APX), as well as other sources for a list price of $19.95. It's a good investment for the serious programmer.
Error Code 0
You can assume that Error Code 0 cannot be trapped. Try this: turn your computer off. With the Atari Basic cartridge in place, turn the machine on again. When the READY appears on the television screen, type, PRINT PEEK(195).
What happened? Remember, we said that the value of the error was stored in location 195 when the error occurred. No error has yet occurred, so the value when the computer is first turned on will be 0.
Error Code 1
This is not really an Error. A 1 is generated and placed in location 195 when the computer makes a status check of a peripheral device (printer, disk drive, etc.) and simply means that the status check was successful. This can be useful information, especially when working with the Atari 850 Interface Module.
Error Codes 2: Memory insufficient
Although you can load or enter the program, your computer doesn't have enough available or free memory to run it. If you have made some modifications to the program, you may be lucky and have enough memory left to save it to disk or cassette. If not, your only recourse is to start over. This is one reason why it's a good idea to save your program occasionally while you are working on it. It won't be necessary to start from scratch if a fatal error occurs.
In most cases, you'll find that you can't trap Error Code 2, because the program will stop before the Trap can be sprung.
Read De Re Atari or check the Atari Basic Reference Manual for tips on how to conserve memory. There are also ways to gain needed memory by doing some reconfiguring of the disk operating system (DOS). Check that manual also.
Sometimes an Error Code 2 results from a failing Memory Module or Basic cartridge. Reseat the Basic cartridge and the RAM and ROM modules. Your error could be a simple case of poor contact between the card edge and the socket.
Error Code 3: Value error
Atari calls this a Value Error. This means your program was expecting a number within a certain range and received a different numerical input. For example:
10 INPUT X
20 ON X GOTO 40,50,60
30 GOTO 10
40 PRINT "LINE 40":END
50 PRINT "LINE 50":END
60 PRINT "LINE 60":END
If any negative number is entered at line 10 then Error Code 3 will result. Try it.
Also try this little experiment:
Your computer was expecting a number in the range of 0 to 255. It didn't know how to handle a number larger than 255, so it awarded you with Error Code 3.
Error Code 4: Too many variables
Your computer is telling you that you have used too many variable names. Atari Basic allows you to use a maximum of 128 different variable names. Check your program listing. If you count less than 128 variables and you still receive an Error Code 4, that means you have some named, but unused, variables hidden away in the variable table.
Now, what's the variable table, you ask? That's a part of your saved program that contains what are called tokens. The table is at the beginning of the program. It is transparent when you list the program on the screen or a printer. The variable table keeps track of the names and number of variables you use.
It's a simple task to clear any unused variables from the variable table. Instead of saving your program, list it to cassette or disk. This creates a version of your program without tokens and strips away the entire variable table. Now type, NEW, and then enter your program. If you save the program now, a new variable table is created containing only those variables that you are currently using in your program.
Error Code 5: String Length Error
This is an easy one. You have tried to put more data into a string than it can handle. Be sure that your string dimensions are correct.
10 DIM A$(6),B$(9)
This short program generates an Error Code 5. But you can avoid it with a change in line 10: 10 DIM A$(15),B$(9).
Error Code 6: Out of Data
If you are using the Basic commands Read and Data, be sure that you have a matched set. There must be one Data statement for each Read statement. Error Code 6 can also arise if you are using the same data more than once in your program and neglect to Restore the line containing the data. Check your program.
The Restore command tells your computer that you want it to read the data at the Restored line. See the Atari Basic Reference Manual for more details on Read, Data, and Restore.
Error Code 7: Number greater than 32767
You have used a reference to an illegal line number. Your Atari doesn't like it when you attempt to refer to lines that are over 32767 with GOTO, GOSUB, or Restore commands. Of course, maybe you want to create this error and trap it. For instance:
10 X=0:TRAP 30
20 X=X+10000: GOSUB X
30 (do something):END
10000 (do something interesting):RETURN
20000 (do something else interesting):RETURN
30000 (do something even more interesting):RETURN
After the fourth pass through line 20, X becomes 40,000. When our program tries to GOSUB to line 40000, then Error Code 7 results; the trap is sprung and the program goes to line 30.
Error Code 8: Input error
Input Statement Error: You've tried to input a string into a numerical variable. X cannot = X$. You can Trap the error and send the program back to the input line for the correct input.
10 TRAP 10
20 INPUT X
30 PRINT X
This simple little program will send the user back to line 10 if anything other than a number is entered.
Error Code 9: Array or Dimension Error
This is one of the most common Basic Errors. Your computer is telling you that you have more than likely neglected to Dimension a string or a numerical array. Or perhaps you have tried to Dimension a string or an array a second time. You only get one chance . . . and you cannot Dimension a numeric array for more than 5460 numbers or a string for more than 2767 characters. Your computer doesn't like it.
Error Code 10: Argument Stack Overflow
You shouldn't see this error when programming in Basic. It is an assembly language problem. I'll leave the explanation to our Assembly language columnist.
Error Code 11: Floating point error
My high school algebra teacher had Ten Commandments of Algebra. One of them was, Thou Shalt Not Divide by Zero! Your computer feels the same way. It'll give you an Error Code 11 every time.
Error Code 11 also might occur if your program is using very large or very small numbers. Chances are that if this is the case, you already are aware of this error. Most programs do not use numbers in the ranges that will generate Error Code 11.
Checking for Error Code 11 can be useful in some programs.
Error Code 12: Line not Found
Shame on you. You've gotten your computer lost by telling it to find a line that doesn't exist in your program. List the line on which the error occurred and make the appropriate change.
Error Code 13: No Matching For
Check the entry for For/Next loops in your manuals. Your program has stumbled across a Next statement without an appropriate For statement and has gotten lost.
This error can also occur if you have a GOSUB statement referring to the line having the Next statement. If you are using For/Next loops (particularly "nested" For/Next loops), take care how you use the Next portion.
Error Code 14: Line too Long
This one is tricky. Atari calls it a "Line too long" error. When a program line is converted into internal format (containing tokens), sometimes it becomes longer than the original. This is especially true if the statement includes a great many numbers. If this error comes up, break the statement into two or more lines.
Error Code 15: GOSUB or For line deleted
You have inadvertently deleted a For statement in a For/Next loop or have deleted a GOSUB. Your program has tripped over the Next (or the Return statement and doesn't know where to go.
This error is similar to Error Code 13 and Error Code 16. It shouldn't come up when the program is first run, but may arise while you are working on your program and are testing your changes by running it.
Error Code 16: Return without GOSUB
Your program has been running merrily along, but has suddenly come across a Return statement and cannot find the appropriate GoSUB. This error will more than likely be generated the first time you run the program after loading it.
You've probably deleted or changed the line containing the GOSUB the last time you worked on the program and forgot to make the appropriate change to the rest of the program. Check your program listing.
Error Code 17: Garbage Error
This is our Garbage Error. Actually, you have quite likely made a syntax error in the line given. List the offending line to the screen. Directly after the line number, your computer says ERROR--then lists the offending line. Look along the line. Your Atari will show you where it detected the error in inverse video.
Remember, this may not be where you made the error, but where the error was detected. Check your statement or statements carefully. Also, remember to delete the ERROR--from the line. Otherwise, you will get another Error Code 17 and an ERROR--ERROR-.
Error Code 18: Invalid string character
You are trying to find a numerical value of a string character and the string (or that portion of the string being checked) contains no numbers. You can't take the value of anything other than numbers within a string. For example:
will return a 12. However,
will give you an Error Code 18. You can use this error quite nicely in some cases.
The above errors are generated by Atari Basic. Next month we'll discuss some of the errors that you may encounter when using the peripheral devices, such as the Atari 810 Disk Drive, the Atari 410 Program Recorder or a printer.
Steve Harding is a freelance technical writer from San Jose. He is the West Coast editor of Hi-Res.