Using USR (was Re: Two ways to torture a comp teacher)

[dempson@actrix.gen.nz (David Empson)]

In article <9408011509.AA10580@phy.mtu.edu>,
Sean M. McAfee <smmcafee@phy.mtu.edu> wrote:
> 
> Quick question:  Has anyone ever used USR() to do anything useful?

Um, maybe.  I've defintely used the & command, and I think I used USR
a few times.

> Also, how 'bout a quick demo of how to use USR()?

The principle is pretty straightforward.  The USR function expects a
single argument, which is evaluated and left in the floating point
accumulator.  Applesoft then does a JSR to location $000A.  Before
using USR, you should place a JMP instruction at $000A to point to
your machine language USR handler.

The machine language program can do whatever it likes, then RTS to
BASIC.  The value in the floating point accumulator is the "result" of
USR.

A minimal "do-nothing" USR function is as follows:

]10 POKE 10,96: REM an RTS instruction
]20 PRINT USR(10)
]RUN
10
]

The USR function will call the RTS instruction, which will return
immediately, and the result of the USR is the argument passed to the
function.

If you want to do anything useful with the argument or return value,
you have to use internal Applesoft calls (all of which are well
documented from various third-party sources, but my favourite is the
disassembly of Applesoft I have, courtesy of the Merlin assembler).

If you want to pass more than one argument to the USR function, or a
non-numeric argument, you have to use the Applesoft parsing routines
and parse additional parameters after the close parenthesis.  One
commonly used syntax is

  USR(arg1),arg2,arg3,arg4   (etc.)

The initial comma isn't required, but it makes the BASIC program
slightly nicer to read.

This requires calling the Applesoft CHKCOMMA and EVAL routines (or
derivatives).
-- 
David Empson
dempson@actrix.gen.nz
Snail mail: P.O. Box 27-103, Wellington, New Zealand