Self-Modifying Atari BASIC: Forced-Read Mode and Programs That Write Programs
Atari BASIC has no statement for changing its own program, but it can still do it. The screen editor can be told to read lines back off the screen as if you had typed them and pressed RETURN. A program can print a few new lines, switch that mode on, stop, and let BASIC "type" them in. A related trick writes lines to a file and ENTERs it. Both were popular in the early 1980s for programs that store their own data, such as phone books, drawing programs and shape editors, and for utilities that generate DATA statements.
What you'll learn: how forced-read mode works and the exact sequence that makes it safe, how to add, replace and delete lines, how to ENTER generated code from a running program and carry on, and a DATA-statement generator.
What you need: Atari BASIC. A disk (or an emulator's H: device) for the file-based method. Every example below was run on Atari BASIC revision C.
1. Why it works
Atari BASIC reads your typing through the screen editor, device E:, on IOCB #0. The editor works with whole screen lines. When you press RETURN, it hands BASIC the logical line under the cursor, which is why you can cursor up to an old line, change it and press RETURN.
The editor's auxiliary byte, ICAX1 of IOCB #0, is at location 842. Normally it holds 12, meaning "keyboard in, screen out". Setting it to 13 puts the editor into forced-read mode, sometimes called "RETURN key mode": each time BASIC asks for a line, the editor takes it straight from the screen at the cursor and moves down, as though RETURN were pressed on every line. A program can therefore:
- Clear the screen and PRINT new program lines, followed by
CONT. - Move the cursor back to the top.
POKE 842,13andSTOP.
BASIC stops, returns to direct mode and asks the editor for input. The editor reads each printed line in turn. Numbered lines are entered into the program, and CONT restarts it at the line after the STOP. That next line must immediately POKE 842,12 to give the keyboard back.
2. A first example: add one line, delete another
10 DIM A(4):FOR I=0 TO 4:A(I)=I*I:NEXT I
20 GRAPHICS 0:POSITION 2,3
30 ? 1000;" DATA ";A(0);",";A(1);",";A(2);",";A(3);",";A(4)
40 ? 900:? "CONT"
50 POSITION 2,0:POKE 842,13:STOP
60 POKE 842,12
70 ? "PROGRAM NOW CONTAINS:":LIST 900,1000
80 RESTORE 1000:FOR I=0 TO 4:READ X:? X;" ";:NEXT I:?
900 REM THIS LINE WILL BE DELETED
Line 30 writes a new DATA line built from the array, line 40 writes a bare 900 (a line number on its own deletes that line, exactly as when you type it) and then CONT. After the run, LIST shows that line 900 has gone and 1000 DATA 0,1,4,9,16 has arrived, and line 80 READs the new data straight away.
Points that matter:
- STOP must be the last statement on its line. CONT resumes at the next line, not the next statement. Put the
POKE 842,12on the following line, as here. - The cursor must start above the lines you printed. STOP prints its own "STOPPED AT LINE 50" message at the cursor, and reading continues below it. Starting the printed lines on row 3 leaves room. If you start too low, lines are skipped. If
CONTis missing or misplaced, the editor keeps reading the screen and the program never resumes. Press RESET to recover. - Variables survive. CONT is a direct-mode command, so nothing is cleared. The new lines are tokenized as you would expect: new names go into the variable table and arrays keep their contents.
- Keep each printed line within the screen editor's limits: a logical line can be up to three screen rows (120 characters, less the margin).
John Anderson's "Self-Modifying Programs" in The Creative Atari uses this method for a small telephone directory that stores each entry as a REM line and saves itself with SAVE. You'll find it on this site as the type-in Self-Modifying Telephone Directory.
3. Letting the user's input become code
Because the lines are printed text, anything you can put in a string you can turn into program code. Two classic uses:
- Saving data inside the program. Print
nnnn DATA ...lines holding the user's high scores, drawing or settings, then SAVE the program. Next time it is LOADed, the data is already there. - Entering a formula at run time. Ask the user for an expression, print it as a line, such as
500 Y=followed by the formula, thenCONT. The program can then GOSUB 500 to evaluate it. This is how some 1980s graphing programs plotted any function you typed in. Wrap the call in TRAP, because the user may type something BASIC rejects. A rejected line is stored with anERROR-marker and stops the program when it runs.
4. The file method: LIST format and ENTER
A LISTed program is simply text lines ending in RETURN (ATASCII 155). Anything your program writes with PRINT # in that form can be ENTERed, and ENTER merges the lines into the current program. That suggests the second technique: write code to a file and ENTER it from inside the program.
There is one surprise. In our tests, ENTER used inside a running program merges the lines and then stops: BASIC returns to READY and the statements after ENTER never run. The cure is to end the file with a direct-mode command that restarts the program. A GOTO to the next line works, and keeps all variables:
10 OPEN #1,8,0,"D:TMP"
20 ? #1;"2000 ? ";CHR$(34);"HELLO FROM LINE 2000";CHR$(34):? #1;"2010 RETURN"
25 ? #1;"GOTO 50"
30 CLOSE #1:X=42
40 ENTER "D:TMP"
50 ? "STILL RUNNING, X=";X
60 GOSUB 2000:END
This printed STILL RUNNING, X=42 and then HELLO FROM LINE 2000. Two details:
- Atari BASIC strings cannot contain a quotation mark, so quotes inside generated lines are written with
CHR$(34). CONTat the end of the file does not work here. We tried it, and BASIC resumed from a stale stopping point and re-ran an earlier line. Use an explicitGOTO.
The file method is slower than forced read, since it needs a disk, but it has no cursor juggling, no screen limits and no risk of the editor running away.
5. A DATA-statement generator
The commonest "program that writes programs" turns a block of memory, such as a redefined character set, a player shape or a machine-language routine, into DATA lines you can ENTER into another program. This one writes the ROM shapes of the letters A to C:
10 REM WRITE THE ROM SHAPES OF A-C AS DATA LINES
20 A=57344+33*8:LN=30000
30 OPEN #1,8,0,"D:SHAPES.LST"
40 FOR C=0 TO 2
50 ? #1;LN;" DATA ";
60 FOR I=0 TO 7:? #1;PEEK(A+C*8+I);:IF I<7 THEN ? #1;",";
70 NEXT I:? #1:LN=LN+10
80 NEXT C:CLOSE #1
90 ? "DONE - NOW TYPE: ENTER ";CHR$(34);"D:SHAPES.LST";CHR$(34)
The file it produced contained:
30000 DATA 0,24,60,102,102,126,102,0
30010 DATA 0,124,102,124,102,102,124,0
30020 DATA 0,60,102,96,96,102,60,0
Load the program that needs the shapes, ENTER "D:SHAPES.LST", and the lines merge in. The character set starts at 57344 ($E000), and the letter A is internal character 33, so its eight bytes start at 57344+33×8. Change the start address and count to dump anything else.
The same idea, writing tokenless text that BASIC will tokenize for you, is behind many type-in utilities: renumbering by LISTing a program and rewriting the line numbers, merging libraries of subroutines, and turning machine code into the DATA loaders printed in magazines.
6. Deleting setup code to free memory
Anderson also suggests deleting lines that are no longer needed. Initialisation code that builds tables or reads long DATA blocks can print its own line numbers (one bare number per line, then CONT) and remove itself once it has run. The memory comes back immediately. The program is now different from the one on disk, so don't SAVE over the original.
Troubleshooting
- The program stops with READY and nothing happens: CONT was not on the screen where the editor reached it, or STOP was not the last statement on its line.
- The screen keeps scrolling and the keyboard is dead: forced read is still on. Press RESET (the editor returns to normal), then check that the line after STOP sets 842 back to 12.
- ERROR- lines appear in the program: a printed line had a syntax error, for example a quote inside a string. Build such lines with
CHR$(34). - ENTER from a program stops it: add a
GOTOback into the program as the last line of the ENTERed file (section 4).
Further reading
- John Anderson, "Self-Modifying Programs", in The Creative Atari (Creative Computing Press, 1983).
- Ian Chadwick, Mapping the Atari, entry for the IOCB #0 block at 832–847, including the forced-read example at 842.
- COMPUTE!, August 1981: an early sample of the technique, cited in Mapping the Atari.
- On this site: CIO and IOCBs: How Atari Input/Output Really Works, Saving, Loading and Merging Atari BASIC Programs, Inside a SAVEd Atari BASIC Program.
Credits
- Picture: Forced-read mode in action: the program printed new lines on the screen, the editor read them back as if typed, and CONT resumed the run. — Program authors; screenshot by the site
- John Anderson, "Self-Modifying Programs", The Creative Atari — John Anderson
- Mapping the Atari — 832-847 IOCB0, location 842 (ICAX1) forced-read mode — AtariArchives.org
