POKE and POKE$ statements

Purpose

Store the byte (POKE), or sequence of bytes (POKE$) at a specified memory location.

Syntax

POKE  [datatype,] address???, datavalue

POKE$ [ASCIIZ,] address???, string_expr

Remarks

The POKE statements and complementary PEEK functions are low-level methods of accessing individual bytes at a specific address in memory.  The data is stored to memory starting at location address???, which is a full 32-bit address.

In its classic form, the POKE statement stores a single byte (8 bits) whose value ranges from 0 to 255.  In its enhanced form, POKE provides the functionality of a dynamic pointer: the datatype parameter specifies the data type and hence the size of the target data to write to the target memory address.  datatype can be any one of BYTE, WORD, DWORD, INTEGER, LONG, QUAD, SINGLE, DOUBLE, EXT, CUR, CUX.

POKE$ stores a string in consecutive bytes where the ASCII code of the first character of the string is stored in the first byte of memory, the next ASCII code is stored in the next byte of memory, and so on, until all bytes in string_expr are stored.  If ASCIIZ is specified, POKE$ writes successive characters to a target address in memory until a terminating $NUL byte is found in the source string.  If no $NUL is found in the string, one is automatically appended to the target buffer.  It is the programmer’s responsibility to ensure that POKE$ does not overrun the target memory area to avoid data corruption or protection faults.

address???

A valid 32-bit memory address, specifying the location in memory where the byte or sequence of bytes should be stored.  Specifying an invalid address can result in a General Protection Fault (GPF).

datavalue

The data value to be stored at address???.

string_expr

A string constant, literal or string expression that specifies the sequence of bytes to be stored in memory starting at the byte referenced by address???.

Restrictions

If address??? (or any byte in the range covered by count&) references an invalid address (memory that is not allocated to the application), Windows will generate a General Protection Fault (GPF) and terminate the application.  GPFs cannot be trapped with an ON ERROR error handler.  Attempting to write into the "code segment" of an application will also generate a GPF, since the code segment is write-protected.

See also

Pointers , PEEK, STRPTR, VARPTR