DATA

Syntax: {Symbol} DATA {@Address,} {Word} DataItem {, DataItem ...}

Function

Write user data to the EEPROM location(s) during program download.

• Symbol is an optional, unique symbol name that will be automatically defined as a constant equal to the location number of the first data item.
• Address is an optional starting location for subsequent DataItems
• DataItem is a constant/expression (0 - 65535) indicating a value or how to store a value.

Quick Facts

Explanation

When you download a program into the BASIC Stamp, it is stored in the EEPROM starting at the highest address (2047) and working towards the lowest address. Most programs don't use the entire EEPROM, so the lower portion is available for other uses. The DATA directive allows you to define a set of data to store in the available EEPROM locations. It is called a "directive" rather than a "command" because it performs an activity at compile-time rather than at run-time (i.e.: the DATAdirective is not downloaded to the BASIC Stamp, but the data it contains is downloaded).

The simplest form of the DATA directive is something like the following:

  DATA          100, 200, 52, 45

This example, when downloaded, will cause the values 100, 200, 52 and 45 to be written to EEPROM locations 0, 1, 2 and 3, respectively. You can then use the READ and WRITE commands in your code to access these locations and the data you've stored there.

DATA uses a counter, called a pointer, to keep track of available EEPROM addresses. The value of the pointer is initially 0. When a program is downloaded, the DATA directive stores the first byte value at the current pointer address, then increments (adds 1 to) the pointer. If the program contains more than one DATA directive, subsequent DATAs start with the pointer value left by the previous DATA. For example, if the program contains:

  DATA          72, 69, 76, 76, 79
  DATA          104, 101, 108, 108, 111

The first DATA directive will start at location 0 and increment the pointer for each data value it stores (1, 2, 3, 4, and 5). The second DATA directive will start with the pointer value of 5 and work upward from there. As a result, the first 10 bytes of EEPROM will look like the following:

What if you don't want to store values starting at location 0? Fortunately, the DATA directive has an option to specify the next location to use. You can specify the next location number (to set the pointer to) by inserting a DataItem in the form @x ;where x is the location number. The following code writes the same data in the table above to locations 100 through 109:

  DATA          @100, 72, 69, 76, 76, 79, 104, 101, 108, 108, 111

In this example, the first DataItem is @100. This tells the DATA directive to store the following DataItem(s) starting at location 100. All the DataItems to the right of the @100 are stored in their respective locations (100, 101, 102... 109).

In addition, the DATA directive allows you to specify new starting locations at any time within the DataItem list. If, for example, you wanted to store 56 at location 100 and 47 at location 150 (while leaving every other location intact), you could type the following:

  DATA          @100, 56, @150, 47

If you have multiple DATA directives in your program, it may be difficult to remember exactly what locations contain the desired data. For this reason, the DATA directive can optionally be prefixed with a unique symbol name. This symbol becomes a constant that is set equal to the location number of the first byte of data within the directive. For example,

MyNumbers       DATA    @100, 72, 73

This would store the values 72 and 73 starting with location 100 and will create a constant, called MyNumbers, which is set equal to 100. Your program can then use the MyNumbers constant as a reference to the start of the data within a READor WRITE command. Each DATA directive can have a unique symbol preceding it, allowing you to reference the data defined at different locations.

There may be a time when you wish to reserve a section of EEPROM for use by your BASIC code, but not necessarily store data there to begin with. To do this, simply specify a DataItem within parentheses, as in:

  DATA          @100, (20)

The above DATA directive will reserve 20 bytes of EEPROM, starting with location 100. It doesn't store any values there, rather it simply leaves the data as it is and increments DATA's location pointer by 20. A good reason to do this is when you have a program already downloaded into the BASIC Stamp that has created or manipulated some data in EEPROM. To protect that section of EEPROM from being overwritten by your next program (perhaps a new version of the same program) you can reserve the space as shown above. The EEPROM's contents from locations 100 to 119 will remain intact. NOTE: This only "reserves" the space for the program you are currently downloading; the BASIC Stamp does not know to "reserve" the space for future programs. In other words, make sure use this feature of the DATA directive in every program you download if you don't want to risk overwriting valuable EEPROM data.

It is important to realize that EEPROM is not overwritten during programming unless it is needed for program storage, or is filled by a DATA directive specifying data to be written. During downloading, EEPROM is always written in 16-byte sections if, and only if, any location within that section needs writing.

DATA can also store the same number in a block of consecutive locations. This is similar to reserving a block of EEPROM, above, but with a value added before the first parenthesis. For example,

  DATA          @100, 0 (20)

This statement writes the value 0 in all the EEPROM locations from 100 to 119.

A common use for DATA is to store strings; sequences of bytes representing text. PBASIC converts quoted text like "A" into the corresponding ASCII character code (65 in this case). To make data entry easier, you can place quotes around a whole chunk of text used in a DATA directive, and PBASIC will understand it to mean a series of bytes (see the last line of code below). The following three DATA directives are equivalent:

  DATA          72, 69, 76, 76, 79
  DATA          "H", "E", "L", "L", "O"
  DATA          "HELLO"

All three lines of code, above, will result in the numbers 72, 69, 76, 76, and 79 being stored into EEPROM upon downloading. These numbers are simply the ASCII character codes for "H", "E", "L", "L", and "O", respectively. See the Example program link at the top for a demonstration of storing and reading multiple text strings.

The EEPROM is organized as a sequential set of byte-sized memory locations. By default, the DATA directive stores bytes into EEPROM. If you try to store a word-size value (ex: DATA 1125) only the lower byte of the value will be stored. This does not mean that you can't store word-sized values, however. A word consists of two bytes, called a low-byte and a high-byte. If you wanted to store the value 1125 using the DATA directive, simply insert the prefix "Word" before the number, as in:

  DATA          Word 1125

The directive above will automatically break the word-size value into two bytes and store them into two sequential EEPROM locations (the low-byte first, followed by the high-byte, or "Little Endian"). In this case, the low-byte is 101 and the high byte is 4 and they will be stored in locations 0 and 1, respectively. If you have multiple word-size values, you must prefix each value with "Word", as in:

  DATA          Word 1125, Word 2000

To retrieve a word-size value, you'll need to use the Word modifier with READ (only available in PBASIC 2.5 syntax). For example,

' {$PBASIC 2.5}

result          VAR     Word

Storage:
  DATA          Word 1125

Main:
  READ 0, Word result
  DEBUG DEC result
  END

This code would write the low-byte and high-byte of the number 1125 into locations 0 and 1 during download. When the program runs, the READ function (with the Word modifier) will retrieve the value out of EEPROM and then display the value on the screen. See the READ and WRITE commands for more information.

Finally, a DataItem may be defined using a simple expression with the binary operators as shown below:

MinLvl          CON     10

myLvl           VAR     Byte

Level1          DATA    MinLvl + 10
Level2          DATA    MinLvl * 5 + 21

Main:
  READ Level2, myLvl                    ' read EE location Level2
  DEBUG DEC myLvl                       ' show value of myLvl (71)
  END