30 a+=1: GO TO 20
40 DATA 1,99,0,201

This will stop with the report E Out of DATA when it has filled in the four bytes you specified.

Using USR to run machine code

To run the machine code, you use the function USR or its –preferred– BANK command variant. In its simplest form USR must be provided with a numeric argument, i.e. the starting address or the bank offset. Its result is the value of the BC register on return from the machine code program, so assuming you type:

PRINT USR 65268

It will return the value 99.

The return address to NextBASIC is stacked in the usual way, so return is by a Z80 ret instruction. You should not use the IY and I registers in a machine code routine that expects to use the NextBASIC interrupt mechanism. To perform the exact same function by using the BANK variant, make the following changes to our program:

10 %a=0
20 BANK NEW %b
30 READ %n : BANK %b POKE %a,%n
40 %a+=1: GO TO 30
50 DATA 1,99,0,201

RUN it and you'll see the E Out of Data error again; Now it's time to execute it and it's done by giving:

PRINT % BANK b USR 0

There are a few more variants of USR that differ in key points and make the life of the machine-code programmer a bit easier. These are:

USR$ addr
BANK n USR$ offset

which call the machine code routine at addr (or offset in bank n). Instead however of returning the 16-bit number found in BC (as with USR addr), USR$ returns a string, defined by the start address returned by the machine-code routine in DE and length in BC.

Additionally, USR as well as USR$ (and their BANK variants) can be provided with optional parameters like:

USR(addr, param1[, param2 [, param3...]]])

USR$(addr, param1[, param2 [, param3...]]])

BANK n USR(addr, param1[, param2 [, param3...]]])

BANK n USR$(addr, param1[, param2 [, param3...]]])

which can be passed to the machine-code routine (instead of just the start address in BC).

If a single additional parameter (param1) is present, this is passed in BC (if it is numeric) or as an address DE and length BC (if it is a string).

The type of the parameter passed to the routine is indicated by the zero flag: if set, the parameter is a string (in DE,BC); if clear, the parameter is a number in BC.