READ

Syntax : READLocation, Variable
Syntax : READLocation, {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

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.