Calling NextZXOS from NextBASIC

When NextBASIC's USR function is used, the code it references is entered with the memory configured with the ROM switched in at the bottom of memory in the address range (000h – 3FFFh) being ROM 3 (the 48 BASIC ROM). The RAM page at the top of memory is Bank 0 and the machine stack resides in this area (unless the CLEAR command has been used to reduce it to somewhere below C000h). As explained in the accompanying documents explaining the NextZXOS API (found in the c:/docs/nextzxos/ folder in your System/Next™ distribution), NextZXOS can only be called with RAM page 7 switched in at the top of memory, the stack held somewhere in that range 4000h to BFE0h, and ROM 2 (the NextZXOS ROM) switched in at the bottom of memory (000h to 3FFFh).

Consequently, it will be necessary to switch both ROM and RAM, and move the stack before and after calling one of the entries in the DOS jump table.

If the CLEAR command has been used so that the NextBASIC stack is below 49120 (BFE0h), then it is not necessary to move the stack. However, we have done so in the following example to demonstrate the technique when this is not the case.

A simple example to call DOS CATALOG:

                org  7000h

mystak          equ  9FFFh                ;arbitrary value picked to be below
                                          ;BFE0h and above 4000h
staksto         equ  9000h                ;somewhere to put BASIC's stack
                                          ;pointer
bankm           equ  5B5Ch                ;system variable that holds the
                                          ;last value output to 7FFDh
port1           equ  7FFDh                ;address of ROM/RAM switching port
                                          ;in I/O map
catbuff         equ  8000h                ;somewhere for DOS to put its cata
                                          ;log
dos_catalog     equ  011Eh                ;the DOS routine to call
demo:           di                        ;unwise to switch RAM/ROM without
                                          ;disabling interrupts
                ld   (staksto),sp         ;save BASIC's stack pointer
                ld   bc,port1             ;the horizontal ROM switch/RAM
                     ;switch I/O address
                ld   a,(bankm)            ;system variable that holds current
                                          ;switch state
                res  4,a                  ;move right to left in horizontal
                                          ;ROM switch (3 to 2)
                or   7                    ;switch in RAM page 7
                ld   (bankm),a            ;must keep system variable up to
                                          ;date (very important)
                out  (c),a                ;make the switch
                ld sp,mystak              ;make sure stack is above 4000h and
                                          ;below BFE0h
                ei                        ;interrupts can now be enabled
                                          ;
                                          ;The above will have switched in
                                          ;the DOS ROM and RAM page 7. The
                                          ;stack has also been located in a
                                          ;"safe" position for calling DOS
                                          ;
                                          ;The following is the code to set
                                          ;up and call DOS CATALOG. This is
                                          ;where yourown code would be
                                          ;placed.
                                          ;
                ld hl,catbuff             ;somewhere for DOS to put the cata
                                          ;log
                ld de,catbuff+1           ;