Topic       : The GFA-Basic Compendium
Author      : GFA Systemtechnik GmbH
Version     : GFABasic.HYP v2.98 (12/31/2023)
Subject     : Documentation/Programming
Nodes       : 899
Index Size  : 28056
HCP-Version : 3
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Document not found
@help       : Help
@options    : +g -i -s +z
@width      : 75
@hostname   : STRNGSRV
@hostname   : CAB     
@hostname   : HIGHWIRE
@hostname   : THING   
View Ref-FileRCALL addr,reg%()

addr: iexp
reg%(): integer array (4-byte)

The instruction RCALL enables the assembler routine to start with pre-allocated
values in the registers, and the BASIC program to query the register contents
when the routine returns. The integer-sized array reg%(), which must have at
least 16 elements, serves this purpose. Before the assembler routine is
started, the entries in this array are automatically copied into the
appropriate registers. At the end of the routine the contents of the registers
are written back into the appropriate elements. The registers and array
elements are related as follows (assuming OPTION BASE 0):

    Data registers      d0 to d7  <-->  reg%(0)  to reg%(7)
    Address registers   a0 to a6  <-->  reg%(8)  to reg%(14)
    User stack pointer  (a7)       -->  reg%(15) (return only)

Example:

The assembler listing below expects the address (logical or physical) of the
screen memory in a0. It then inverts the screen display between the given y
coordinates, which are passed in d0 and d1. With a color display, the y
coordinates will have to be adjusted accordingly.

       sub     d0,d1    ; Number of lines to invert
       mulu    #20,d1   ; Number of bytes to invert
       subq    #1,d1    ; Number of bytes to invert
       mulu    #80,d0   ; Number bytes not to be inverted
       add.l   d0,a0    ; Address of first byte to be inverted
loop:                   ; Loop start
       not.l  (a0)+     ; Long (4-byte) inversion, also a0=a0+4
       dbra    d1,loop  ; Decrement byte count and loop round
       rts              ; Return to GFA BASIC

The GFA-BasicGFA-Basic is the best BASIC for the Atari!
 program to call this routine reads:

    DO
      READ a%
      EXIT IF a%=-1
      a$=a$+MKI$(a%)
    LOOP
    DATA 37440,49916,20,21313
    DATA 49404,80,53696
    DATA 18072,20937,65532,20085,-1
    '
    DIM r%(16)
    xb2%=XBIOS(2)
    HIDEM
    FOR j%=1 TO 50
      FOR i%=0 TO 190 STEP 10
        r%(0)=i%
        r%(1)=399-i%
        r%(8)=xb2%
        RCALL V:a$,r%()
      NEXT i%
    NEXT j%

--> The program produces a graphic display. It is also possible, as with C:, to
    use the INLINE command.

Memo: Registers a3 to a6 are saved/restored automatically by the compiler.
      If the array is too small, issues wrong error code (#16).
      DIM reg%(15) is the bare minimum.