Download BASIC User`s Manual

TSC BASIC User's Manual
11.3
THE USR FUNCTION FOR 6809
When BASIC encounters a USR function in an expression it evaluates
the argument, converts the result to a 16 bit 2's complement integer,
and places the result in memory at MEMEND-4. Next, BASIC gets a 16 bit
address from memory at MEMEND-2. This address tells BASIC where the
user supplied subroutine is located. If these bytes are zero, an error
will be issued. If they are non-zero, a JSR to the address specified
will be executed. This address may either be set manually or by using
the POKE statement. MEMEND represents the FLEX memory end pointer.
If
memory end is $7FFF, then the USR argument will be at $7FFF-4 or $7FFB,
and the USR vector will be at $7FFF-2 or $7FFD. You must know where the
FLEX memory end is to use USR! The FLEX memory end is stored at $CC2B
and $CC2C. The following explanation assumes a memory end of $7FFF.
In the user's routine, it is only necessary to access the locations
hex 7FFB and 7FFC to retrieve the argument passed from BASIC. To return
a value from the subroutine, simply write a 16 bit value into locations
hex 7FFB and 7FFC. When the subroutine is finished, do an RTS to
return. It is very important that the executing subroutine returns with
the stack pointers at the same location as when it was entered.
The
subroutine should also not use more than 256 bytes of stack space during
execution.
After the subroutine returns control to BASIC the USR function call
will assume the value returned in locations hex 7FFB and 7FFC.
The
following example demonstrates the mechanics of using USR without
performing any specific task.
300 POKE HEX("7FFD"),HEX("C1")
310 POKE HEX("7FFE"),HEX("OO")
320 A1 = 10 * USR(6)
The machine code may look like this:
ORG
LDX
***
LDX
STX
RTS
$C100
$7FFB
#VALUE
$7FFB
GET PASSED ARGUMENT
ACTUAL CODE HERE
GET VALUE TO BE RETURNED
SAVE FOR BASIC TO USE
SHOULD END WITH RTS
Lines 300 and 310 in the BASIC code set up the address of the machine
language routine ($C1OO) and puts it in location $7FFD (the USR vector).
Line 320 will pass the value 6 to the machine language routine.
After
returning from the routine, the value returned will be multiplied by 10
and put in the variable A1.
The assembly language code
shown
demonstrates a method of passing the parameter to and from the user
subroutine.
-67-