# READ

READ Examples

Syntax : READ Location, Variable
Syntax : READ Location, {WORD} Variable {, {WORD} Variable, ...}

## Function

- Location Location is a variable/constant/expression* (0 - 255 on BS1, 0 - 2047 on all other BASIC Stamp models) that specifies the EEPROM address to read from.
- Variable is a variable (usually a byte) where the value is stored.*

* Note: expressions are not allowed as arguments on the BS1.

*Note: The optional arguments require PBASIC 2.5.

## Quick Facts

| BS1 | BS2, BS2e, and BS2sx | BS2p, BS2pe, and BS2px
Range of EEPROM locations | 0 to 255 | 0 to 2047 | 0 to 2047 (see notes below)
Special Notes | n/a | READ only works with current program slot on BS2e and BS2sx. | READ works with any program slot as set by the STORE command.
Related Commands | WRITE, EEPROM | WRITE, DATA | WRITE, DATA, STORE
PBASIC 2.5 Syntax Options | n/a | Multiple sequential variables may be read from the Scratchpad RAM, and the optional WORD modifier may be specified to retrieve 16-bit values.

## Explanation

The EEPROM is used for both program storage (which builds downward from address 255 on BS1, 2047 on all other BASIC Stamp models) and data storage (which builds upward from address 0). The READ instruction retrieves a value from any EEPROM address and stores it in Variable. When the optional Word modifier ($PBASIC 2.5 required) is used, the low byte of Variable is read from Location, the high byte of Variable from Location + 1.

Any location within the EEPROM can be read (including your PBASIC program's tokens) at run-time. This feature is mainly used to retrieve long-term data from EEPROM; data stored in EEPROM is not lost when the power is removed.

The following READ command retrieves the value at location 100 and stores it into the variable called Result:

    SYMBOL  result  = B2

    Main:
      READ 100, result
      END

    result  VAR     Byte

    Main:
      READ 100, result
      END

The EEPROM is organized as a sequential set of byte-sized memory locations. The READ command retrieves byte-sized values from EEPROM. This does not mean that you can't read word-sized values, however. A word consists of two bytes, called a low-byte and a high-byte. If you wanted to read a word-sized value, you can use two READ commands and a word-size variable (along with some handy modifiers). For example:

    SYMBOL  result  =  W1                   ' word-sized variable
    SYMBOL  resLo   =  B2                   ' low-byte of W1
    SYMBOL  resHi   =  B3                   ' high-byte of W1

    EEPROM  (101, 4)                        ' Store word-sized value

    Main:
      READ 0, resLo
      READ 1, resHi
      DEBUG #result
      END

    result  VAR     Word

    DATA    Word    1125                    ' Store word-sized value

    Main:
      READ 0, result.LowByte
      READ 1, result.HighByte
      DEBUG DEC ? result
      END

This code uses the EEPROM or DATA directive to write the low-byte and high-byte of the number 1125 into locations 0 and 1 during download. When the program runs, the two READ commands will read the low-byte and high-byte out of EEPROM (reconstructing it in a word-size variable) and then display the value on the screen.

When using $PBASIC 2.5 syntax, word-sized variables can be retrieved with a single READ statement, as well as multiple items from consecutive locations.

    ' {$PBASIC 2.5}

    idNum   VAR     Word
    score   VAR     Byte

    ID_Rec  DATA    Word 1125, 75           ' Store multiple items

    Main:
      READ ID_Rec, Word idNum, score        ' Read multiple variables
      DEBUG DEC ? idNum                     ' Display them
      DEBUG DEC ? score
      END

Note that the EEPROM and DATA directives store data in the EEPROM before the program runs, however, the WRITE command can be used to store data while the program is running. Additionally, the EEPROM locations can be read an unlimited number of times, but EEPROM locations can be worn out by excessive writes. See the WRITE command for more information.

When using the READ and WRITE commands, take care to ensure that your program doesn't overwrite itself. On the BS1, location 255 holds the address of the last instruction in your program. Therefore, your program can use any space below the address given in location 255. For example, if location 255 holds the value 100, then your program can use locations 0-99 for data.

On other BASIC Stamp models, you'll need to view the Memory Map of the program before you download it, to determine the last EEPROM location used.

On the BS2p, BS2pe, and BS2px the READ and WRITE commands can affect locations in any program slot as set by the STORE command. See the STORE command for more information.

Go to Welcome page

BASIC Stamp Help Version 2.5.4

Copyright © Parallax Inc.

8/8/2012