Atari USR

I own an Atari 600XL, but don't have a complete manual. What does the USR statement do? I've seen it in several programs, such as A = USR(1536). What is the 1536 for? Why can't you enter USR(710) to change the color of the screen?

USR looks like any other BASIC function, but is the gateway from Atari BASIC to machine language. It does not work like POKE or PEEK, which can be used to change and read memory locations like 710, which holds the background color of a GRAPHICS 0 screen. An understanding of machine language is essential in creating your own USR calls, but there are many plug-in subroutines (published in our books and in COMPUTE!) that you can add to your program.

For machine language programmers, USR lets you pass parameters (variable values or expressions) to the machine language program. A = USR(n,x,y,z) would start the 6502 executing the code at memory location n (instead of executing the BASIC interpreter). Since there are three parameters in the example, the number 3 will be the first item on the 6502 stack (use PLA to read a byte off the top of the stack into the accumulator). If there are no parameters, a zero is used, and you must pull this zero off before you use RTS to return to BASIC. The rest of the parameters are converted to 16-bit unsigned integers, and placed in order on the stack. Each parameter becomes a two-byte number which is found on the stack high byte first, then low byte: The stack after the call A = USR(1536,5,65535,2562):

The next two bytes are the return address—1 of the BASIC interpreter, since JSR (which is how USR calls the ML) stores this address on the stack.

Since USR is a function, you can't use it by itself, but must use a statement like X = USR(1536). The actual variable you use doesn't matter, but the ML program can pass a value back to BASIC by storing the low byte of the number in $D4 and the high byte in $D5. This value will be assigned to the variable used in the USR statement.