PEEK and POKE
                               =============


PEEK, PEEK_W, PEEK_L, PEEK_F

PEEK is a function which returns the contents of the specified memory
location. PEEK has four forms which will access a byte (8 bits), a word
(16 bits), a long word (32 bits), or a float (48 bits). PEEK may be
referenced from the system variables:

If the first parameter of PEEK is preceded by an exclamation mark, then the
address of the peek is in the system variables or referenced via the system
variables.

There are two variations: direct and indirect references. For direct
references, the exclamation mark is followed by another exclamation mark
and an offset within the system variables.

For indirect references, the exclamation mark is followed by the offset of
a pointer within the system variables, another exclamation mark and an
offset from that pointer.

PEEK may also be referenced from the SuperBASIC variables if the first
parameter of PEEK is preceded by a backslash, then the address of the peek
is in the SuperBASIC variables or referenced via the SuperBASIC variables.
There are two variations: direct and indirect references.

For direct references, the backslash is followed by another backslash and
an offset within the SuperBASIC variables.

For indirect references, the backslash is followed by the offset of a
pointer within the SuperBASIC variables, another backslash and an offset
from that pointer.

Syntax:

        address:= numeric_expression
        | !! numeric_expression
        | ! numeric_expression ! numeric_expression
        | \\ numeric_expression
        | \ numeric_expressionI \ numeric_expression

        PEEK(address) {byte access}
        PEEK_W(address) {word access}
        PEEK_L(address) {long word access}
        PEEK_F(address) {floating point access}

Examples:

        i.    PRINT PEEK(12245) {byte contents of location 12245}
        ii.   PRINT PEEK_W(12) {word contents of locations 12 and 13}
        iii.  PRINT PEEK_L(1000) {long word contents of location 1000}
        iv.   ramt = PEEK_L(! !$20) {find the top of RAM $20 bytes on from
              the base of the system variables}
        v.    job1 = PEEK_L(!$68!4) {find the base address of Job 1 (4
              bytes on from base of Job table)}
        vi.   dal = PEEK_W(\\$94) {find the current data line number
        vii.  n6 = PEEK_W(\$18\2+6*8) {find the name pointer for the 6th
              name in the name table}
        viii. nl6 = PEEK(\$20\n6) {...and the length of the name}
        ix.   n6$ = PEEK$(\$20\n6+1, nl6) {...and the name itself}

Warning:

        For word, long word and float access the specified address must be
        an even address.


PEEKS, PEEKS_W, PEEKS_L, PEEKS_F

Supervisor mode access to I/O hardware. Syntax etc as above.


PEEK$

PEEK$ will return a string with the number of supplied bytes starting from
the supplied address. The bytes need not, of course, be text.

Syntax:

        start_address   := numeric_expression
        number_of_bytes := numeric_expression

        PEEK$ (start_address, number_of_bytes)

Example:

        PRINT PEEK$(123456,20) {will display the 20 bytes from address
        123456}


PEEKS$

Supervisor mode access to I/O hardware. Syntax as for PEEK$ above.



POKE, POKE_W, POKE_L POKE_F

POKE allows a memory location to be changed. For word, long word and float
accesses the specified address must be an even address.

POKE has four forms which will access a byte (8 bits), a word (16 bits), a
long word (32 bits), and a floating point number (48 bits).

POKE may be referenced form the system variables if the first parameter of
POKE is preceded by an exclamation mark, then the address of the poke is in
the system variables or referenced via the system variables. There are two
variations: direct and indirect references.

For direct references, the exclamation mark is followed by another
exclamation mark and an offset within the system variables.

For indirect references, the exclamation mark is followed by the offset of
a pointer within the system variables, another exclamation mark and an
offset from that pointer.

POKE may also be referenced from the SuperBASIC variables if the first
parameter of POKE is preceded by a backslash, then the address of the poke
is in the SuperBASIC variables or referenced via the SuperBASIC variables.
There are two variations: direct and indirect references.

For direct references, the backslash is followed by another backslash and
an offset within the SuperBASIC variables.

For indirect references, the backslash is followed by the offset of a
pointer within the SuperBASIC variables, another backslash and an offset
from that pointer.

POKE allows more than one value to be POKEd at a time. For POKE_W, POKE_L
and POKE_F, the address may be followed by a number of values to poke in
succession.

For POKE the address may be followed by a number of values to poke in
succession and the list of values may include strings. If a string is
given, all the bytes in the string are POKEd in order. The length is not
POKEd.

Syntax:

        address:= numeric_expression
        | !! numeric_expression
        | ! numeric_expression ! numeric_expression
        | \\ numeric_expression
        | \ numeric_expressionI \ numeric_expression
        data:= numeric_expression

        POKE address, data [ * ,data | string * ] {byte access}
        POKE_W address, data [ * ,data * ] {word access}
        POKE_L address, data [ * ,data * ] {long word access}
        POKE_F address, data [ * ,data * ] {float access}

Example:

        i.   POKE 12235,0 {set byte at 12235 to 0}
        ii.  POKE_L 131072,12345 {set long word at 131072 to 12345}
        iii. POKE_W ! !$8E,3 {set the auto-repeat speed to 3}
        iv.  POKE !$B0!2, 'WIN' {change the first three characters of
             DATA_USE to WIN}
        v.   POKE_F! $C4! $14A, (scx% / scy%) / (1280 / 800)
             Set the screen geometry, where scx%/scy% are the nominal screen
             size and 1280 / 800 are the physical screen dimensions

Warning:

Poking data into areas of memory used by the OS can cause the system to
crash and data to be lost. Poking into such areas is not recommended.


POKES, POKES_W, POKES_L, POKES_F

Supervisor mode access to I/O hardware. Syntax as above.


POKE$

POKE$ will poke the supplied string of bytes into memory, starting from the
supplied address.

Syntax:

        start_address := numeric_expression
        POKE$ start_address, string
        POKE$ start_address, strin)

Example:

        POKE$ 131072,"hello" {will put the string "hello" into address
        131072}

Comment:

PEEK$ and POKE$ can accept all the extended addressing facilities of PEEK
and POKE. Indeed, POKE$ is identical to POKE which can now accept string
parameters.


POKES$

Supervisor mode access to I/O hardware. Syntax as for POKE$ above.


Manual status
=============

This manual is probably copyright 1990 Tony Tebby QJUMP

Updated to include PEEK_F and POKE_F by pjw, 2022 May 04