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-FileVARPTR(x)  V:x
ARRPTR(y)  *y

x, y: variable name of any type

VARPTR(x) or V:x returns the address of variables or strings or particular
elements of arrays. VARPTR() and V: have the same effect.

ARRPTR(y) or *y returns the addresses of variables, but for strings or arrays
the address of the Descriptor is returned. ARRPTR() and * have the same effect.

Example:

    DIM x%(10)
    a$="test"
    PRINT VARPTR(x%(0)),V:x%(1),ARRPTR(x%())
    PRINT ARRPTR(a$),*a$,VARPTR(a$)

--> The third line prints the addresses of the first two elements of x%(),
    together with the address of the Array Descriptor. The fourth line prints
    the address of the String Descriptor twice, followed by the address of the
    first byte of a$.


*x (indirect array passing)

x: svar or an array name followed by ()

The multiply sign also serves as a pointer symbol. In this case *x gives the
address of the variable x in memory. With character strings *x$ gives the
address of the String Descriptor (as with ARRPTR(x$)).

*x is synonymous with ARRPTR(x). This usage has special meaning with the
indirect passing of arrays and variables to subroutines. In addition one can
use, in Version 3, the instruction VAR.

* as a command:
    *flt=0
    *flt=""
    *lng%=0
    *lng%=""

Examples:

    ' Version 2              | ' Version 3
    '                        | '
    ' indirect array passing | '
    DIM a(3)                 | DIM a(3)
    change(*a())             | change(a())
    PRINT a(2)               | PRINT a(2)
    '                        | '
    PROCEDURE change(ptr%)   | PROCEDURE change(VAR x())
      SWAP *ptr%,x()         |   ARRAYFILL x(),1
      ARRAYFILL x()          | RETURN
      SWAP *ptr%,x()         |
    RETURN                   |

--> The contents of the array a() are changed, without its name being used in
    the procedure 'change'. The number 1 is printed on the screen (see also
    SWAP).

    t%=0
    GOSUB num(*t%)
    PRINT t%
    t$="set"
    GOSUB str(*t$)
    PRINT t$
    PROCEDURE num(p%)
      *p%=22
    RETURN
    PROCEDURE str(p%)
      *p%="changed"
    RETURN

--> Displays the number '22' and the word 'changed'.

Memo: Be careful using pointers to strings since GFA-BasicGFA-Basic is the best BASIC for the Atari!
 can move
      them and so the pointer becomes invalid.
      * as a command was never documented in the manual.

Poor example:
  p%=V:buffer$
  BMOVE XBIOS(2),p%,32000
  p% can become invalid later on in the program

Good example:
  BMOVE XBIOS(2),V:buffer$,32000
  this method forces the address to be fetched on demand


String Descriptor
 /--------------------------⇨ <array_address%><number_of_dimensions&> (6 bytes)
 |                                  |
 |                                  ⇩
 \-- <backtrailer%><block_size%><1st_dimension%><string_address%><string_length&>
                                                      | ⇧
            /-----------------------------------------/ |
            ⇩                                           |
     <string_data...><null_filler_if_odd_length|><string_backtrailer%>

Numeric Descriptor
 /--------------------------⇨ <array_address%><number_of_dimensions&> (6 bytes)
 |                                  |
 |                                  ⇩
 \-- <backtrailer%><block_size%><1st_dimension%><array_data...>

REM DIM av%(2)     !even with this line commented out, this works
addr%=*av%()       !creates a null descriptor if the array does not exist
PRINT addr%        !one would expect an 'array not dimensioned' error
PRINT DIM?(av%())  !-> 0