# P65 BASIC The P65 comes with a BASIC in ROM, in the style of Applesoft: Microsoft BASIC with floating point numbers (9 digits), strings, arrays, and a set of extra commands for the P65's graphics chip (TMS9918), the flash storage and the machine itself. It descends from [mist64/msbasic](https://github.com/mist64/msbasic) with Applesoft-compatible commands added (see the notes at the top of `rom/fpp65.a65`). This document describes every command and function. All examples with a result below them were run on the real ROM in the emulator, and are checked again by `python tools/basic_doc.py` (`tests/test_basic_doc.py`). Notation: `UPPER CASE` is typed as it is, `` is something you supply, `[ ... ]` is optional, `...` can repeat. ## Contents 1. [Using BASIC](#1-using-basic) 2. [Numbers, strings, variables and operators](#2-numbers-strings-variables-and-operators) 3. [Program control](#3-program-control) 4. [Flow of control](#4-flow-of-control) 5. [Variables and data](#5-variables-and-data) 6. [Text output and input](#6-text-output-and-input) 7. [Functions](#7-functions) 8. [Graphics](#8-graphics) 9. [Sprites](#9-sprites) 10. [Flash storage](#10-flash-storage) 11. [The machine: memory, I/O, machine code](#11-the-machine-memory-io-machine-code) 12. [Errors](#12-errors) 13. [Not implemented](#13-not-implemented) --- ## 1. Using BASIC After a reset the screen shows the banner and the prompt `Ok`. You type a line and press Return. * A line **with a number** is stored in the program. Typing a number alone deletes that line. * A line **without a number** is executed at once (*immediate mode*). * Several statements go on one line, separated by a colon `:`. * Keywords can be typed in lower case, they are stored in upper case. * **Ctrl-C** stops a running program: `Break in `. `CONT` continues it. * The screen is 40 columns by 24 rows. A long line wraps to the next row. ```basic PRINT "HELLO" ``` ```text HELLO ``` A program is a list of numbered lines. `RUN` starts it at the lowest line number: ```basic 10 PRINT "HELLO" 20 PRINT "WORLD" RUN ``` ```text HELLO WORLD ``` Output is shown as it appears on the screen. A number is printed with a space in front of it (or a minus sign) and a space behind it. Each command ends with the prompt `Ok`, which is left out of the results in this document. ```basic PRINT 1,2,3 PRINT -1;-2;-3 ``` ```text 1 2 3 -1 -2 -3 ``` --- ## 2. Numbers, strings, variables and operators ### Numbers Numbers are floating point with about 9 significant digits, from about 1E-38 to 1.7E38. Decimal numbers can have an exponent (`1.5E3`). Hexadecimal constants start with `$`. ```basic PRINT 1E10;1E-5;123456789;0.1+0.2 PRINT $FF;$100;$FF+1 ``` ```text 1E+10 1E-05 123456789 .3 255 256 256 ``` Commands that need a whole number (`POKE`, `PEEK`, addresses, `HPLOT` coordinates) take the whole part of the value and complain with `Illegal quantity` when it is out of range. ### Variables A variable name is a letter followed by letters and digits. **Only the first two characters count** (`AB1` and `AB2` are the same variable). The last character can be a type marker: | name | holds | |---|---| | `A` | real number | | `A%` | integer (-32767 to 32767) | | `A$` | string (up to 255 characters) | `A` and `A$` and `A%` are three different variables. A variable that was not set is 0 (or the empty string). Arrays have their own names too: `A(1)` is not `A`. ```basic AB1=5:AB2=6 PRINT AB1;AB2 ``` ```text 6 6 ``` ```basic A=1:A$="STRING":A%=7 PRINT A;A$;A% ``` ```text 1 STRING 7 ``` An integer variable holds the number rounded **down** (as `INT` does): ```basic A%=3.9 PRINT A% A%=-3.9 PRINT A% ``` ```text 3 -4 ``` ### Operators From the highest to the lowest priority: | operator | meaning | |---|---| | `( )` | parentheses | | `^` | power | | `-` (unary), `NOT` | negation (also logical NOT) | | `*` `/` | multiply, divide | | `+` `-` | add, subtract (`+` also joins strings) | | `=` `<` `>` `<=` `>=` `<>` | comparison: gives -1 (true) or 0 (false) | | `AND` | logical and (bit by bit on 16 bits) | | `OR` | logical or | ```basic PRINT 2^10;10/4;3*4-1 PRINT 5>3;5<3;5=5 PRINT 7 AND 3;7 OR 8;NOT 0 PRINT "A"<"B";"HELLO"="HELLO" ``` ```text 1024 2.5 11 -1 0 -1 3 15 -1 -1 -1 ``` Strings are joined with `+` and compared character by character: ```basic A$="X":B$=A$+"Y" PRINT B$;LEN(B$) ``` ```text XY 2 ``` --- ## 3. Program control ### NEW Deletes the program and clears all variables. ```basic 10 PRINT "A" NEW LIST ``` ```text ``` ### RUN `RUN` starts the program at its first line, `RUN ` at the given line. It clears the variables first. ```basic 10 PRINT "A" 20 PRINT "B" RUN 20 ``` ```text B ``` ### LIST `LIST` lists the whole program. `LIST ` lists one line, `LIST ,` a range. Keywords are listed in upper case and spaced out. ```basic 10 A=1:PRINT A 20 FOR I=1 TO 2:NEXT LIST ``` ```text 10 A = 1: PRINT A 20 FOR I = 1 TO 2: NEXT ``` ```basic 10 PRINT "A" 20 PRINT "B" 30 PRINT "C" LIST 20,30 ``` ```text 20 PRINT "B" 30 PRINT "C" ``` ### DEL `DEL ,` deletes the lines from `first` to `last` (both included). ```basic 10 PRINT "A" 20 PRINT "B" 30 PRINT "C" DEL 20,20 LIST ``` ```text 10 PRINT "A" 30 PRINT "C" ``` ### END, STOP, CONT `END` stops the program quietly. `STOP` stops it with the message `Break in ` and `CONT` carries on with the next statement (it also works after Ctrl-C). In this example the program stops after printing 1 and 2, and `CONT` prints the 3: ```basic 10 FOR I=1 TO 3 20 PRINT I; 30 IF I=2 THEN STOP 40 NEXT RUN CONT ``` ```text 1 2 Break in 30 3 ``` ### CLEAR Sets all variables to 0 or the empty string and forgets arrays, `FOR` loops and `GOSUB` returns. The program stays. ```basic A=5 CLEAR PRINT A ``` ```text 0 ``` ### REM A comment: the rest of the line is ignored. ```basic 10 REM THIS IS A COMMENT 20 PRINT "X" : REM AND THIS TOO RUN ``` ```text X ``` --- ## 4. Flow of control ### GOTO, GOSUB, RETURN, POP `GOTO ` continues at that line. `GOSUB ` calls a subroutine, `RETURN` comes back to the statement after the `GOSUB`. `POP` throws away the most recent return address (to leave a subroutine with a `GOTO`). ```basic 10 GOSUB 100 20 PRINT "BACK" 30 END 100 PRINT "SUB" 110 RETURN RUN ``` ```text SUB BACK ``` ```basic 10 GOSUB 100 20 PRINT "NOT REACHED" 30 END 40 PRINT "AFTER POP" 50 END 100 POP 110 GOTO 40 RUN ``` ```text AFTER POP ``` ### ON ... GOTO, ON ... GOSUB `ON GOTO ,,...` jumps to the line with that position (1 is the first). If the number is 0 or larger than the list, the next statement runs. `ON ... GOSUB` works the same for subroutines. ```basic 10 FOR I=0 TO 3 20 ON I GOTO 100,200 30 PRINT "NONE "; 40 GOTO 300 100 PRINT "ONE "; 110 GOTO 300 200 PRINT "TWO "; 300 NEXT RUN ``` ```text NONE ONE TWO NONE ``` ### FOR, TO, STEP, NEXT `FOR = TO [STEP ]` repeats the statements up to `NEXT []`. The step is 1 unless given and may be negative. The loop body always runs at least once. ```basic 10 FOR I=10 TO 1 STEP -3 20 PRINT I; 30 NEXT RUN ``` ```text 10 7 4 1 ``` Loops can be nested. A single `NEXT` can close several loops: `NEXT J,I`. ```basic 10 FOR I=1 TO 2 20 FOR J=1 TO 3 30 PRINT I*J; 40 NEXT J,I RUN ``` ```text 1 2 3 2 4 6 ``` ### IF ... THEN ... ELSE `IF THEN ` jumps to the line, `IF THEN ` runs the statements when the condition is true (not 0). When it is false, the rest of the line is skipped. `ELSE` is an extra of the P65: put a **colon in front of it**; it runs when the condition is false. ```basic 10 FOR A=1 TO 5 STEP 4 20 IF A>3 THEN PRINT "BIG":ELSE PRINT "SMALL" 30 NEXT RUN ``` ```text SMALL BIG ``` ```basic 10 A=1 20 IF A=1 THEN PRINT "ONE":PRINT "TWO" 30 IF A=2 THEN PRINT "NOT SHOWN" 40 PRINT "LAST" RUN ``` ```text ONE TWO LAST ``` --- ## 5. Variables and data ### LET `LET =`. The word `LET` is optional. ```basic LET A=3 B=A*2 PRINT A;B ``` ```text 3 6 ``` ### DIM `DIM ([,...])` creates an array whose indexes run from 0 to `max`. An array that is used without `DIM` has indexes 0 to 10. Arrays can have several dimensions and any type. `DIM` is not allowed twice for the same array (`Redim'd array`). ```basic 10 DIM A(3),B$(2),C(1,1) 20 A(2)=7:B$(1)="HI":C(1,1)=5 30 PRINT A(2);B$(1);A(0);C(1,1) RUN ``` ```text 7 HI 0 5 ``` ### DATA, READ, RESTORE `DATA` holds constants (numbers and strings) in the program. `READ ,...` takes them one by one from the first `DATA` in the program. `RESTORE` starts again from the first one. Reading past the last one gives `Out of data`. ```basic 10 DATA 1,2,3,"HELLO" 20 READ A,B,C,D$ 30 PRINT A;B;C;D$ 40 RESTORE 50 READ X 60 PRINT X RUN ``` ```text 1 2 3 HELLO 1 ``` ### DEF FN, FN `DEF FN ()=` defines a one-argument function that is called as `FN ()`. It can only be defined inside a program. ```basic 10 DEF FN SQ(X)=X*X 20 PRINT FN SQ(7) RUN ``` ```text 49 ``` ### SWAP `SWAP ,` exchanges the values of two variables of the same type (a P65 extra). ```basic 10 A=1:B=2 20 SWAP A,B 30 PRINT A;B RUN ``` ```text 2 1 ``` --- ## 6. Text output and input ### PRINT `PRINT ...` writes to the screen. Items are numbers, strings and expressions. * `;` between items writes them one after the other (a number has a space or minus sign in front of it and a space behind it), * `,` moves to the next tab stop (every 16 columns), * a `;` or `,` at the end keeps the cursor on the line, otherwise `PRINT` ends the line, * `TAB()` moves to column `n` (1 is the first), `SPC()` writes `n` spaces. ```basic PRINT "A";"B","C" PRINT 1;2,3 ``` ```text AB C 1 2 3 ``` ```basic PRINT SPC(3);"X" PRINT TAB(5);"Y" ``` ```text X Y ``` ### HOME Clears the text screen and puts the cursor in the top left corner. In `HGR` it does not clear the picture. ```basic PRINT "SOMETHING" HOME PRINT "AFTER HOME" ``` The screen is empty after `HOME`, only `AFTER HOME` is left on it. ### HTAB, VTAB `HTAB ` moves the cursor to the column (1 is the first), `VTAB ` to the row (1 is the top). ```basic HTAB 10:PRINT "X" ``` ```text X ``` ```basic HOME VTAB 5 HTAB 20 PRINT "CENTRE" ``` ### NORMAL, INVERSE `INVERSE` makes the text that is printed next appear dark on light, `NORMAL` returns to the usual look. ```basic INVERSE PRINT "INVERTED" NORMAL PRINT "NORMAL" ``` ```text INVERTED NORMAL ``` ### INPUT `INPUT ["";][,...]` waits for a line. Without a prompt it shows `?`. With several variables the values are typed separated by commas. ```basic 10 INPUT "NAME";N$ 20 PRINT "HELLO ";N$ RUN BOB ``` ```text NAMEBOB HELLO BOB ``` ```basic 10 INPUT A,B 20 PRINT A+B RUN 3,4 ``` ```text ?3,4 7 ``` `INPUT` can only be used in a program (`Illegal direct` otherwise). ### GET `GET ` reads one key without waiting for Return and without showing it. The program waits until a key is pressed. ```basic 10 GET A$ 20 PRINT "KEY ";A$ RUN Z ``` ```text KEY Z ``` --- ## 7. Functions A function gives a value and is used in expressions: `PRINT SQR(16)`. ### Numeric | function | result | |---|---| | `ABS(x)` | absolute value | | `SGN(x)` | -1, 0 or 1 | | `INT(x)` | the whole number not larger than `x` (rounds down) | | `SQR(x)` | square root | | `EXP(x)` | e to the power `x` | | `LOG(x)` | natural logarithm | | `SIN(x)` `COS(x)` `TAN(x)` `ATN(x)` | trigonometry in radians | | `RND(x)` | random number from 0 up to (not including) 1 | ```basic PRINT INT(-3.5);SGN(-2);ABS(-4);SQR(16) ``` ```text -4 -1 4 4 ``` ```basic PRINT ATN(1)*4 PRINT SIN(1);COS(1) PRINT LOG(10);EXP(1) ``` ```text 3.14159266 .841470985 .540302306 2.30258509 2.71828183 ``` `RND(1)` gives the next random number; for a dice, `INT(RND(1)*6)+1`: ```basic 10 D=INT(RND(1)*6)+1 20 PRINT D>=1 AND D<=6 RUN ``` ```text -1 ``` ### Strings | function | result | |---|---| | `LEN(a$)` | number of characters | | `LEFT$(a$,n)` | the first `n` characters | | `RIGHT$(a$,n)` | the last `n` characters | | `MID$(a$,start[,n])` | `n` characters from position `start` (1 is the first); without `n` the rest | | `ASC(a$)` | character code of the first character | | `CHR$(n)` | the character with code `n` | | `STR$(x)` | the number as a string | | `VAL(a$)` | the number in the string (0 if it does not start with one) | ```basic PRINT LEFT$("HELLO",2);MID$("HELLO",2,3);RIGHT$("HELLO",2) PRINT MID$("HELLO",3) ``` ```text HEELLLO LLO ``` ```basic PRINT STR$(12);VAL("3.5E2");ASC("A");CHR$(66);LEN("ABC") ``` ```text 12 350 65 B 3 ``` ### System | function | result | |---|---| | `FRE(0)` | free memory for the program, in bytes | | `POS(0)` | the column of the cursor (0 is the first) | | `PEEK(a)` | the byte at address `a` | | `WPEEK(a)` | the 16 bit word at `a` and `a+1` (low byte first) | | `VPEEK(a)` | the byte at address `a` in the video memory (VRAM, 0 to 16383) | | `USR(x)` | calls machine code, see [section 11](#11-the-machine-memory-io-machine-code) | ```basic PRINT FRE(0)>20000 PRINT POS(0) ``` ```text -1 0 ``` --- ## 8. Graphics The P65 has two screen modes, both from the TMS9918 video chip. | mode | command | what it is | |---|---|---| | text | `TEXT` | 40 x 24 characters (the usual screen) | | `HGR` | `HGR` | graphics: 256 x 160 pixels, 16 colours, with a few lines of text at the bottom | Other modes of the chip (Graphics I, Multicolor) can be set by hand with `VDP` and `VPOKE`, see below. **Colours.** The colour numbers are those of the TMS9918: | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | |---|---|---|---|---|---|---|---| | transparent | black | medium green | light green | dark blue | light blue | dark red | cyan | | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | |---|---|---|---|---|---|---|---| | medium red | light red | dark yellow | light yellow | dark green | magenta | grey | white | > **Colour limit of the chip.** In `HGR` the colour is not stored for each pixel but for each group of > **8 pixels side by side** in one row: one colour for the lit pixels and one for the dark ones. > Drawing in a new colour makes **all lit pixels of that group of 8** take the new colour. Two > lines of different colours that run through the same group of 8 will change each other's colour > near the crossing. Steep lines touch few pixels of a group, shallow lines many. This is how the > chip works; keep differently coloured drawings apart. ### HGR Switches to graphics mode, clears the picture and sets the drawing colour to white. Text can still be printed; it appears in the lines at the bottom. ```basic HGR HCOLOR=15 HPLOT 0,0 TO 255,159 ``` ### TEXT Switches back to the text mode. ### HCOLOR= `HCOLOR=` sets the drawing colour for `HPLOT`, `HLIN` and `VLIN` (0 to 15). Colour 0 draws with the background and so **erases**. It only works in `HGR` (`Illegal quantity` in text mode). ```basic HGR HCOLOR=3 HPLOT 10,10 TO 100,50 HCOLOR=0 HPLOT 10,10 TO 100,50 ``` ### HPLOT Draws in the `HCOLOR`. Coordinates: `x` is 0 to 255, `y` is 0 to 159 (otherwise `Illegal quantity` and nothing is drawn). | form | draws | |---|---| | `HPLOT x,y` | a point | | `HPLOT x1,y1,x2,y2` | a line, both end points included | | `HPLOT x1,y1 TO x2,y2` | the same line | | `HPLOT x1,y1 TO x2,y2 TO x3,y3 ...` | a chain of lines, each starts where the previous one ended | ```basic HGR HPLOT 128,80 HPLOT 0,159,255,159 HPLOT 10,10 TO 100,10 TO 100,120 TO 10,10 ``` A star: ```basic 10 HGR 20 FOR I=0 TO 255 STEP 16 30 HPLOT 128,80 TO I,0 40 HPLOT 128,80 TO I,159 50 NEXT RUN ``` A sine wave: ```basic 10 HGR 20 FOR X=0 TO 255 30 HPLOT X,80+INT(60*SIN(X/20)) 40 NEXT RUN ``` ### HLIN, VLIN `HLIN , AT ` draws a horizontal line, `VLIN , AT ` a vertical one. The two numbers can be in either order. ```basic HGR HLIN 10,200 AT 80 VLIN 20,140 AT 128 HLIN 255,0 AT 159 ``` Fifteen colours: ```basic 10 HGR 20 FOR C=1 TO 15 30 HCOLOR=C 40 HLIN 0,255 AT C*10 50 NEXT RUN ``` ### COLOR `COLOR [,]` or `COLOR ,` sets the colours of the text screen (and the border in graphics mode). Note: **no equals sign** (`COLOR=` is for the Apple, not here). ```basic COLOR 1,14 COLOR 15 COLOR ,6 ``` ### VDP `VDP ,` writes a register of the video chip (0 to 7). Use it to set a screen mode by hand. Register 1 keeps the interrupt bit (see [section 11](#11-the-machine-memory-io-machine-code)). ```basic VDP 7,$F1 ``` ### VPOKE, VPEEK `VPOKE
,` writes a byte into the 16 KB video memory (VRAM), `VPEEK(
)` reads one. Addresses are 0 to 16383. ```basic VPOKE 100,77 PRINT VPEEK(100) ``` ```text 77 ``` In text mode the screen is the 960 bytes of the name table (default address 0 in VRAM, 40 columns per row); writing a character code there puts it on the screen: ```basic HOME VPOKE 0,65 ``` --- ## 9. Sprites There are 32 sprites, each 8 x 8 pixels, one colour each. You define the shape, then place the sprite. ### DEFSPR `DEFSPR ,,,,,,,,` defines the shape number `shape`. The eight numbers are the rows from top to bottom, one bit per pixel (the highest bit is the left pixel). ```basic DEFSPR 0,$FF,$81,$81,$81,$81,$81,$81,$FF DEFSPR 1,$18,$3C,$7E,$FF,$FF,$7E,$3C,$18 ``` ### DRAW `DRAW ,,,,` shows a sprite: `sprite` is 1 to 32, `colour` 0 to 15, `shape` the number given to `DEFSPR`, and `x`, `y` the position in pixels. Drawing again with the same sprite number moves it. A colour of 0 makes it invisible. Not more than four sprites fit on one scan line. ```basic DEFSPR 0,$FF,$81,$81,$81,$81,$81,$81,$FF DEFSPR 1,$18,$3C,$7E,$FF,$FF,$7E,$3C,$18 HGR DRAW 1,15,0,100,80 DRAW 2,3,1,120,80 ``` A moving sprite: ```basic 10 DEFSPR 1,$18,$3C,$7E,$FF,$FF,$7E,$3C,$18 20 FOR X=0 TO 240 30 DRAW 1,9,1,X,80 40 NEXT RUN ``` --- ## 10. Flash storage About 1 MB of the Pico's flash is a small file system for programs and data. Names are up to 8 characters plus a three letter type; without a type, `SAVE` and `LOAD` use `.BAS` and the binary commands `.BIN`. Names are strings, so `SAVE "GAME"+STR$(L)` works. See [STORAGE.md](STORAGE.md) for the details of the file system and for copying files to and from a PC. ### SAVE, LOAD `SAVE ""` stores the program, `LOAD ""` replaces the program in memory with a stored one. ```basic 10 PRINT "HELLO FROM DISK" SAVE "HELLO" NEW LOAD "HELLO" RUN ``` ```text HELLO FROM DISK ``` ### CATALOG Lists the files (name, size) and the free space. ```basic 10 PRINT "X" SAVE "ONE" SAVE "TWO" CATALOG ``` ```text ONE.BAS BAS 11 TWO.BAS BAS 11 2 FILES, 1008 KB FREE ``` ### ERASE, RENAME `ERASE ""` deletes a file, `RENAME "",""` renames it. ```basic 10 PRINT "X" SAVE "OLD" RENAME "OLD","NEW" CATALOG ERASE "NEW" CATALOG ``` ```text NEW.BAS BAS 11 1 FILES, 1012 KB FREE 0 FILES, 1016 KB FREE ``` ### BSAVE, BLOAD, BRUN `BSAVE "",
,[,]` stores a piece of memory as a binary file; `` is the address where `BRUN` starts it (0, the default, means the first byte). `BLOAD ""[,
]` loads it back, to the address it was saved from unless one is given. `BRUN ""` loads the file and calls it as machine code; the program can come back with `RTS`. ```basic 10 POKE 2048,169:POKE 2049,66:POKE 2050,141:POKE 2051,0:POKE 2052,9:POKE 2053,96 20 BSAVE "PROG",2048,6 30 BRUN "PROG" 40 PRINT PEEK(2304) RUN ``` ```text 66 ``` (The six bytes are the machine code `LDA #66 : STA $0900 : RTS`.) Errors of the storage are normal BASIC errors that `ONERR GOTO` can catch (see [section 12](#12-errors)): `File not found`, `Disk full`, `Bad file name`, `File type mismatch`, `File exists`, `File too big`, `File corrupt`, `No storage`, `Address range`. --- ## 11. The machine: memory, I/O, machine code The memory map and the I/O registers are described in [MEMORY_MAP.md](MEMORY_MAP.md): 32 KB of RAM at $0000-$7FFF, the I/O page at $8000, the ROM above it. ### PEEK, POKE `PEEK(
)` reads a byte, `POKE
,` writes one (0 to 255). Addresses are 0 to 65535. ```basic POKE 1024,65 PRINT PEEK(1024) ``` ```text 65 ``` ### WPEEK, WPOKE `WPOKE
,` writes a 16 bit value (low byte at `address`), `WPEEK(
)` reads one. ```basic WPOKE 1024,$1234 PRINT WPEEK(1024) PRINT PEEK(1024);PEEK(1025) ``` ```text 4660 52 18 ``` ### I/O registers The three LEDs are at address 32768 ($8000): bits 0 to 2 are LED0 to LED2 (1 = on). Reading gives `$F8` plus the bits. ```basic POKE 32768,5 PRINT PEEK(32768) ``` ```text 253 ``` The keyboard register is 32769 ($8001): bit 7 is set when a key has been pressed (`PEEK(32769)>127`) and the key code is in the other bits. Writing anything to it clears the flag. (`GET` does this for you.) ### The frame counter The ROM counts the 60 Hz frame interrupts of the video chip in three bytes at addresses 992, 993 and 994 (a 24 bit number, low byte first), so you can time things: ```basic 10 T=PEEK(992)+256*PEEK(993) 20 FOR I=1 TO 100:NEXT 30 U=PEEK(992)+256*PEEK(993) 40 PRINT U>T RUN ``` ```text -1 ``` `POKE 996,0` turns the frame interrupt off, `POKE 996,1` on again. ### WAIT `WAIT
,[,]` waits until `(PEEK(address) XOR xor) AND mask` is not 0. This waits for the next frame (bit 0 of the frame counter changes): ```basic 10 WAIT 992,1 20 PRINT "FRAME" RUN ``` ```text FRAME ``` ### CALL `CALL
` runs machine code at `address`. The code comes back with `RTS`. ```basic POKE 768,96 CALL 768 PRINT "BACK" ``` ```text BACK ``` ### USR `USR(x)` calls machine code through a jump instruction at addresses 10 to 12 (`POKE 10,76` is the `JMP`, then the address low and high byte). The value `x` is passed in the floating point accumulator; whatever the routine leaves there is the result. A routine that only does `RTS` returns `x`. ```basic POKE 768,96 POKE 10,76:POKE 11,0:POKE 12,3 PRINT USR(3) ``` ```text 3 ``` ### & (ampersand) `&` jumps to the machine code at the vector at address 1013 ($03F5), which has to contain a `JMP` instruction (as in the Apple). The text after the `&` is where the routine can read its parameters. ### HIMEM:, LOMEM: `HIMEM:
` sets the highest address BASIC uses (the top of the program memory and the strings), `LOMEM:
` the lowest address for variables. They are used to reserve memory for machine code and graphics tables. ```basic HIMEM: 30000 PRINT FRE(0)<20000 ``` ```text 0 ``` ### TRACE, NOTRACE `TRACE` prints the number of every line that is executed, `NOTRACE` stops it. ```basic 10 TRACE 20 A=1 30 B=2 40 NOTRACE 50 PRINT "DONE" RUN ``` ```text # 20 # 30 # 40 DONE ``` ### The monitor `CALL -151` starts the machine code monitor (prompt `*`). The most used commands: | typed | does | |---|---| | `800` | shows the byte at $0800 | | `800.80F` | shows the bytes from $0800 to $080F | | `800: A9 05 8D 00 80 60` | puts bytes into memory from $0800 | | `800L` | disassembles from $0800 (20 instructions) | | `800G` | runs the code at $0800 | | `Ctrl-C` | back to BASIC | --- ## 12. Errors When a statement fails, BASIC stops the program with a message and the line number, for example `Syntax error in 20`, and returns to `Ok`. `ONERR GOTO ` makes the program carry on at the given line when an error happens, instead of stopping. In that routine `PEEK(222)` gives the error code. `RESUME` runs the statement that failed again (so the routine has to fix the cause first, or leave with `GOTO`). ```basic 10 ONERR GOTO 100 20 PRINT 1/0 30 PRINT "DONE" 40 END 100 PRINT "ERROR";PEEK(222) 110 GOTO 30 RUN ``` ```text ERROR 133 DONE ``` The error codes: | code | message | |---|---| | 0 | `NEXT without FOR` | | 16 | `Syntax error` | | 22 | `RETURN without GOSUB` | | 42 | `Out of data` | | 53 | `Illegal quantity` | | 69 | `Overflow` | | 77 | `Out of memory` | | 90 | `Undef'd statement` | | 107 | `Bad subscript` | | 120 | `Redim'd array` | | 133 | `Division by zero` | | 163 | `Type mismatch` | | 176 | `String too long` | | 224 | `Undef'd function` | The storage commands add their own codes: 160 plus the storage error number (see [STORAGE.md](STORAGE.md)). --- ## 13. Not implemented These keywords exist in the ROM but do nothing useful: * `STORE` and `HEX$` give `Advanced feature error`. * `HEX$` is a placeholder; for hexadecimal numbers use `$` constants and the monitor. Applesoft commands that are **not** in this BASIC: `PLOT` (use `HPLOT`), `HGR2`, `XDRAW`, `SHLOAD`, `RECALL`, `FLASH`, `PR#`, `IN#`, and the low resolution graphics `GR`, `HLIN`/`VLIN` with the lores meaning (`HLIN` and `VLIN` exist here as commands of `HGR`). A line typed with one of these gives `Syntax error` (`HGR2` first runs `HGR`). `ROT=` and `SCALE=` and `SPEED=` are not keywords either, they are taken as an assignment to an ordinary variable and do nothing.