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-FileBYTE{x}
WORD{x} (INT{x})
LONG{x} ({x})
FLOAT{X}
CARD{x}
SINGLE{x}
DOUBLE{x}
CHAR{x}

x: iexp

By means of these commands one can read certain variable types starting from a
given address, or write them to an address.

As a function, e.g. y=BYTE{x}, one can read, starting from the address x, and
as an instruction, e.g. BYTE{x}=y, one can write, again starting from address
x.

It is important when using WORD{}, CARD{}, LONG{}, FLOAT{}, SINGLE{}, and
DOUBLE{} that only even numbered addresses are specified, since
otherwise an address error occurs and three bombs are displayed.

Type      Meaning
BYTE{}    Reads/writes a byte.

CARD{}    Reads/writes a 2-byte unsigned integer (0-65535).

WORD{}    Reads/writes a 2-byte signed integer.
          Instead of WORD{} you may use INT{} which has the same effect.

LONG{}    Reads/writes a 4-byte integer.
          Instead of LONG{x} you may use {x} which has the same effect.

FLOAT{}   Reads/writes an 8-byte variable in GFA-BasicGFA-Basic is the best BASIC for the Atari!
 3 floating-point
          format.

SINGLE{}  Reads/writes a 4-byte floating-point variable in IEEE
          single-precision format.

DOUBLE{}  Reads/writes an 8-byte floating-point variable in IEEE
          double-precision format.

CHAR{}    Reads a string of bytes until a null byte (zero) is encountered, or
          writes the specified string of bytes and appends a null byte.
          Particularly important for communication with C routines and
          GEMDOS().

With x%=LONG{adr%} the variable x% is assigned the long-word value found at the
address adr%, and with LONG{adr%}=x% the value of x% is written as a long-word
to the address adr%.

With SINGLE{} and DOUBLE{} it is possible to read or write in IEEE format, used
by some 'C' compilers. So, with GFA-BasicGFA-Basic is the best BASIC for the Atari!
, a number in the Single or Double
format can be converted and displayed in hexadecimal:

    a$=SPACE$(4)
    SINGLE{V:a$}=1.2345
    PRINT HEX$(CVL(a$),8)

or

    a$=SPACE$(8)
    DOUBLE{V:a$}=1.2345
    PRINT HEX$(LONG{V:a$},8)
    PRINT HEX$(LONG{V:a$+4},8)

Some functions mentioned above approximately correspond: LONG{} for instance
corresponds to LPEEK(). However, LONG{} is quicker than LPEEK(), although it
will not work in the Supervisor mode. Attempting to access protected
memory locations (0 to 2047) with LONG{} will result in a bus error, with two
bombs displayed.

Examples:

    adr%=XBIOS(2)
    t%=TIMER
    FOR i%=1 TO 4000
      VOID LONG{adr%}
    NEXT i%
    PRINT (TIMER-t%)/200
    '
    t%=TIMER
    FOR i%=1 TO 4000
      VOID LPEEK(adr%)
    NEXT i%
    PRINT (TIMER-t%)/200
    '
    PRINT x
    FLOAT{*x}=PI
    PRINT x

--> The first part of the example shows that LONG{} works more quickly than
    LPEEK(), and the second part demonstrates writing a floating-point number
    indirectly to a variable.

    BYTE{XBIOS(2)+100*160}=&HFF
    CARD{XBIOS(2)+102*160}=&HFFFF
    LONG{XBIOS(2)+104*160}=&HFFFFFFFF
    '
    a$="test"+CHR$(0)
    PRINT CHAR{V:a$};
    '
    b$=SPACE$(5)
    CHAR{V:b$}="word"
    PRINT b$,ASC(RIGHT$(b$))

--> First, some values are written directly to the screen memory and appear as
    lines. Then a$ is assigned conventionally, with a zero byte added, where
    upon it is read with CHAR{} and printed. Then the word 'word' is written
    into the space made for it by assigning b$ as five spaces. The reassigned
    b$ is then printed, together with the ASCII code of its last character, to
    prove that a null byte was indeed added to 'word'. The output is thus
    'test', 'word', and '0'.

Memo:
    t$=CHAR{addr%} does not check the resulting string size when compiled.
    Always test your code in the interpreter!