HX-20 Technical Note

Extending the BASIC Interpreter

1. BASIC Token Address

The following program will list the token number and execution address of the BASIC commands and functions:

100 DEFDBL A-Z:OPEN "O",1,"LPT0:"
110 T=&H80:PRINT #1,"COMMANDS":PRINT #1:N%=0:GOSUB 120
115 T+&HFF80:PRINT #1,"FUNCTIONS":PRINT #1:N%=1:GOSUB 120
117 END
120 X=&H5A6+5*N%:CNT=PEEK(X):M=PEEK(X+1)*256+PEEK(X+2)
122 A=PEEK(X+3)*256+PEEK(X+4):M1=M
124 IF CNT>0 THEN PRINT #1,"TOKEN";TAB(16);"ADDR"
130 IF M=0 THEN 190 ELSE IF (PEEK(M)=0) OR (CNT=0) THEN 190
140 CNT=CNT-1:PRINT #1,HEX$(T);TAB(6);
150 IF PEEK(M) < 128 THEN PRINT #1,CHR$(PEEK(M));:M=M+1:GOTO 150
160 PRINT #1,CHR$(PEEK(M) AND 127);TAB(16);:M=M+1
170 IF(A<>M1) THEN PRINT #1,HEX$(PEEK(A)*256+PEEK(A+1));:A=A+2
180 PRINT #1:T=T+1:GOTO 130<
190 PRINT #1:RETURN

Note that function tokens all start with a byte of &HFF. The BASIC programs are stored as follows:

Each line is formatted as follows:

Note that the program text is held at MEMSET when BASIC is running, but is copied into the application file when any other application is used.

2. Memory locations

3. Entry Points

4. Extending BASIC

BASIC can be extended by adding new device drivers, commands or functions, or any combination of these.

The code to implement the new facilities must be located on ROM or be copied to a protected area above all other applications. I have a utility program that performs this function. The code must conform to the following format:

The HOOK routine is executed every time BASIC is warm started. It must link in the new device drive by adding it to the list of drivers. It must also link in the new commands or functions to the next free command/function vector table. On entry to the HOOK routine (X) points at the exissting Log—on message. This may be printed using the routine at &H917E, and (X) pointed at a new routine if required. Alternatively (X) should be preserved during the HOOK routine. The HOOK routine must terminate by jumping back to the RTS at the start of the code. The RTS and associated null bytes are replaced by a JMP instruction if any additional extended BASICs are linked in.

5. Device drivers

The simplest extension is to add a new device driver. The device requires a device table, used to inform BASIC of the addresses used by the device. The format of the device table is as follows:

The DCB address must be placed in the first free location in the DCB address table at &H657. A free entry contains &H0000. Any device intialisation must be performed in the HOOK routine.

If a call to a routine in the DCB results in an error, the routine can either load B with a suitable error number and jump to &H8433. or it can jump to &HA9DB to ABORT (producing the Abort... message).

Note that all devices are closed during an abort. If the device requires initialization as a result of the abort, the address of an initialization routine must be linked in to HOOKABTD (&H63C—E; contains a JMP instruction).

If you want to load a program from an input device, you must link in code to HKLOAD (&H5E2—5). This must compare the value in (A) with the device number (the offset in the DCB address table). If a match occurs, jump to LODCNT (&HA6D0), otherwise return to the ERROR routine at &H8433 with a suitable error number in (B).

Commands

TKN (&HFB,C) points at the command token. You must ensure that the token is valid for the current routine, if not you must either generate an error or execute the command routine for the next command vector table (if in use). Note that if you jump to the command routine for the next table, (B) must contain the command token. If the token is valid you should process the remainder of the command. TKN must be left pointing at a ":" or null byte on return to the interpreter.

Note that if your command spans more than one line you must ensure that you update &HAC,D. You should use TKN to scan over the program.

The command routine must do an RTS to return to the interpreter.

Functions

On entry to the function routine, TKN is pointing at the first character beyond the function token. You must use TKN to scan back to the &HFF byte to locate the function code. If the token is invalid you should either jump to the error routine, or jump to the function routine for the next function vector table (if in use). Note that (B) must contain the function code in this case.

If the token is valid, it may be necessary to process the function parameters before placing the function result in FPACC. &H85 must contain the type of the result:

Byte	Contents
2	Integer in FPACC+6,7
3	String descriptor in FPACC+5 - FPACC+7
4	Real in FPACC+4 - FPACC+7
8	Double in FPACC - FPACC+7

On return to the interpreter TKN must point at the first character beyond the function (normally beyond the closing right parenthesis). The function routine must return using an RTS instruction.

6. User Routines

User routines can, contrary to the BASIC manual, return a result of any type. All that is required is to change the value in FPACC and &H85 to suit the new value.

Copyright © Julian Wald 1997-2002
Most recent revision August 2002