269 lines
18 KiB
HTML
269 lines
18 KiB
HTML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="6" MadCap:lastHeight="94" MadCap:lastWidth="853" MadCap:disableMasterStylesheet="true" MadCap:tocPath="" MadCap:InPreviewMode="false" MadCap:PreloadImages="false" MadCap:RuntimeFileType="Topic" MadCap:TargetType="WebHelp" lang="en-us" xml:lang="en-us" MadCap:PathToHelpSystem="../../../" MadCap:HelpSystemFileName="Default.xml" MadCap:SearchType="Stem">
|
|
<head><title>DATA</title>
|
|
<link href="../../SkinSupport/MadCap.css" rel="stylesheet" />
|
|
<link href="../../Resources/Stylesheets/BSE_Help.css" rel="stylesheet" />
|
|
<script src="../../SkinSupport/MadCapAll.js" type="text/javascript">
|
|
</script>
|
|
</head>
|
|
<body>
|
|
<h1 class="code">DATA</h1>
|
|
<div class="ImagePlusCaption">
|
|
<div class="Col2">
|
|
<p>
|
|
<img src="../../graphics/pgm_icon2.gif" border="0" alt="BS2 icon" title="BS2 icon" />
|
|
<img src="../../graphics/pgm_icon2e.gif" border="0" alt="BS2e icon" title="BS2e icon" />
|
|
<img src="../../graphics/pgm_icon2sx.gif" border="0" alt="BS2sx icon" title="BS2sx icon" />
|
|
<img src="../../graphics/pgm_icon2p.gif" border="0" alt="BS2p icon" title="BS2p icon" />
|
|
<img src="../../graphics/pgm_icon2pe.gif" border="0" alt="BS2pe icon" title="BS2pe icon" />
|
|
<img src="../../graphics/pgm_icon2px.gif" border="0" alt="BS2px icon" title="BS2px icon" />
|
|
</p>
|
|
</div>
|
|
<p style="text-align: right;"><a href="../ExampleTopics/DataEx.htm" target="" title="" alt="" class="MCXref_0" xrefformat="{paratext}">DATA Example</a>
|
|
</p>
|
|
<p> </p>
|
|
</div>
|
|
<p class="clear"> </p>
|
|
<p> </p>
|
|
<p class="PlainText">Syntax: {<i>Symbol</i>} <span class="keyword_in_text">DATA</span>
|
|
{@<i>Address</i>,} {Word} <i>DataItem </i>{,<i> DataItem ...</i>}</p>
|
|
<h2>Function</h2>
|
|
<p class="PlainText">Write user data to the EEPROM location(s) during program download.
|
|
|
|
</p>
|
|
<ul>
|
|
<li value="1"><b><i>Symbol</i></b> is an optional, unique symbol name that will be
|
|
automatically defined as a constant equal to the location number of the first
|
|
data item.</li>
|
|
<li value="2"><b><i>Address</i></b> is an optional starting location for subsequent
|
|
<i>DataItems</i></li>
|
|
<li value="3"><b><i>DataItem</i></b> is a constant/expression (0 - 65535) indicating a value
|
|
or how to store a value.</li>
|
|
</ul>
|
|
<h2>Quick Facts</h2>
|
|
<table cellpadding="4" cellspacing="0" border="1" style="caption-side: top;width: 100%;">
|
|
<col />
|
|
<col />
|
|
<tr bgcolor="#CFCFCF">
|
|
<td width="15%" align="center"> </td>
|
|
<td width="85%" align="center">All BS2 Models</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" bgcolor="#CFCFCF">Special Notes</td>
|
|
<td>Writes values to EEPROM during download in blocks of 16 bytes. Writes byte- or word-sized values. Can be used to decrease program size.</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" bgcolor="#CFCFCF">Related Commands</td>
|
|
<td align="center"><a href="READ.htm" target="" title="" alt="" class="MCXref_0" xrefformat="{paratext}">READ</a>, <a href="WRITE.htm" target="" title="" alt="" class="MCXref_0" xrefformat="{paratext}">WRITE</a></td>
|
|
</tr>
|
|
</table>
|
|
<h2>Explanation</h2>
|
|
<p class="PlainText">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 <span class="keyword_in_text">DATA</span> 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 <span class="keyword_in_text">DATA</span>directive is not downloaded to the BASIC Stamp, but the data it contains is downloaded).</p>
|
|
<p class="PlainText">The simplest form of the <span class="keyword_in_text">DATA</span> directive is something like the following:</p><pre class="BScode" xml:space="preserve">
|
|
DATA 100, 200, 52, 45
|
|
</pre>
|
|
<p class="PlainText">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
|
|
<span class="keyword_in_text">READ</span> and <span class="keyword_in_text">WRITE</span> commands in your code to access these locations and
|
|
the data you've stored there.</p>
|
|
<p class="PlainText"><span class="keyword_in_text">DATA</span> 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 <span class="keyword_in_text">DATA</span> 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
|
|
<span class="keyword_in_text">DATA</span> directive, subsequent <span class="keyword_in_text">DATA</span>s start with the pointer value left
|
|
by the previous <span class="keyword_in_text">DATA</span>. For example, if the program contains:</p><pre class="BScode" xml:space="preserve">
|
|
DATA 72, 69, 76, 76, 79
|
|
DATA 104, 101, 108, 108, 111
|
|
</pre>
|
|
<p class="PlainText">The first <span class="keyword_in_text">DATA</span> directive will start at location 0 and increment the pointer
|
|
for each data value it stores (1, 2, 3, 4, and 5). The second <span class="keyword_in_text">DATA</span> 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:</p>
|
|
<table width="100%" cellpadding="4" cellspacing="0" border="1">
|
|
<tr>
|
|
<td width="20%" align="center" bgcolor="#CFCFCF" rowspan="2"> </td>
|
|
<td align="center" bgcolor="#CFCFCF" colspan="10">EEPROM Location (address)</td>
|
|
</tr>
|
|
<tr>
|
|
<td width="8%" align="center" bgcolor="#CFCFCF">0</td>
|
|
<td width="8%" align="center" bgcolor="#CFCFCF">1</td>
|
|
<td width="8%" align="center" bgcolor="#CFCFCF">2</td>
|
|
<td width="8%" align="center" bgcolor="#CFCFCF">3</td>
|
|
<td width="8%" align="center" bgcolor="#CFCFCF">4</td>
|
|
<td width="8%" align="center" bgcolor="#CFCFCF">5</td>
|
|
<td width="8%" align="center" bgcolor="#CFCFCF">6</td>
|
|
<td width="8%" align="center" bgcolor="#CFCFCF">7</td>
|
|
<td width="8%" align="center" bgcolor="#CFCFCF">8</td>
|
|
<td width="8%" align="center" bgcolor="#CFCFCF">9</td>
|
|
</tr>
|
|
<tr>
|
|
<td width="20%" align="center" bgcolor="#CFCFCF">Contents</td>
|
|
<td width="8%" align="center">72</td>
|
|
<td width="8%" align="center">69</td>
|
|
<td width="8%" align="center">76</td>
|
|
<td width="8%" align="center">76</td>
|
|
<td width="8%" align="center">79</td>
|
|
<td width="8%" align="center">104</td>
|
|
<td width="8%" align="center">101</td>
|
|
<td width="8%" align="center">108</td>
|
|
<td width="8%" align="center">108</td>
|
|
<td width="8%" align="center">111</td>
|
|
</tr>
|
|
</table>
|
|
<p> </p>
|
|
<p class="PlainText">What if you don't want to store values starting at location 0? Fortunately,
|
|
the <span class="keyword_in_text">DATA</span> 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
|
|
<i>DataItem</i> 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:</p><pre class="BScode" xml:space="preserve">
|
|
DATA @100, 72, 69, 76, 76, 79, 104, 101, 108, 108, 111
|
|
</pre>
|
|
<p class="PlainText">In this example, the first <i>DataItem </i>is @100. This tells the <span class="keyword_in_text">DATA</span> directive
|
|
to store the following <i>DataItem</i>(s) starting at location 100. All the
|
|
<i>DataItems</i> to the right of the @100 are stored in their respective locations
|
|
(100, 101, 102... 109).</p>
|
|
<p>In addition, the <span class="keyword_in_text">DATA</span> directive allows you to specify new starting locations
|
|
at any time within the <i>DataItem</i> 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:</p><pre class="BScode" xml:space="preserve">
|
|
DATA @100, 56, @150, 47
|
|
</pre>
|
|
<p class="PlainText">If you have multiple <span class="keyword_in_text">DATA</span> directives in your program, it may be difficult
|
|
to remember exactly what locations contain the desired data. For this reason, the
|
|
<span class="keyword_in_text">DATA</span> 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,</p><pre class="BScode" xml:space="preserve">
|
|
MyNumbers DATA @100, 72, 73
|
|
</pre>
|
|
<p class="PlainText">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 <span class="keyword_in_text">READ</span>or <span class="keyword_in_text">WRITE</span> command. Each <span class="keyword_in_text">DATA</span> directive can have a unique symbol preceding
|
|
it, allowing you to reference the data defined at different locations.</p>
|
|
<p class="PlainText">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 <i>DataItem</i> within parentheses, as in:</p><pre class="BScode" xml:space="preserve">
|
|
DATA @100, (20)
|
|
</pre>
|
|
<p class="PlainText">The above <span class="keyword_in_text">DATA</span> 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 <span class="keyword_in_text">DATA</span>'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 <span class="keyword_in_text">DATA</span> directive in every program you download if you don't
|
|
want to risk overwriting valuable EEPROM data.</p>
|
|
<p class="PlainText">It is important to realize that EEPROM is not overwritten during programming
|
|
unless it is needed for program storage, or is filled by a <span class="keyword_in_text">DATA</span> 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. </p>
|
|
<p class="PlainText"><span class="keyword_in_text">DATA</span> 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,</p><pre class="BScode" xml:space="preserve">
|
|
DATA @100, 0 (20)
|
|
</pre>
|
|
<p class="PlainText">This statement writes the value 0 in all the EEPROM locations from 100 to 119.</p>
|
|
<p>A common use for <span class="keyword_in_text">DATA</span> 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 <span class="keyword_in_text">DATA</span> directive, and PBASIC will understand
|
|
it to mean a series of bytes (see the last line of code below). The following
|
|
three <span class="keyword_in_text">DATA</span> directives are equivalent: </p><pre class="BScode" xml:space="preserve">
|
|
DATA 72, 69, 76, 76, 79
|
|
DATA "H", "E", "L", "L", "O"
|
|
DATA "HELLO"
|
|
</pre>
|
|
<p class="PlainText">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.</p>
|
|
<p class="PlainText">The EEPROM is organized as a sequential set of byte-sized memory locations.
|
|
By default, the <span class="keyword_in_text">DATA</span> directive stores bytes into EEPROM. If you try to
|
|
store a word-size value (ex: <span class="keyword_in_text">DATA</span> 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 <span class="keyword_in_text">DATA</span> directive, simply insert the prefix
|
|
"Word" before the number, as in:</p><pre class="BScode" xml:space="preserve">
|
|
DATA Word 1125
|
|
</pre>
|
|
<p class="PlainText">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 "<i>Little Endian</i>"). 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:</p><pre class="BScode" xml:space="preserve">
|
|
DATA Word 1125, Word 2000
|
|
</pre>
|
|
<p class="PlainText">To retrieve a word-size value, you'll need to use the Word modifier with
|
|
<span class="keyword_in_text">READ</span> (only available in PBASIC 2.5 syntax). For example,</p><pre class="BScode" xml:space="preserve">
|
|
' {$PBASIC 2.5}
|
|
|
|
result VAR Word
|
|
|
|
Storage:
|
|
DATA Word 1125
|
|
|
|
Main:
|
|
READ 0, Word result
|
|
DEBUG DEC result
|
|
END
|
|
</pre>
|
|
<p class="PlainText">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 <span class="keyword_in_text">READ</span> function (with
|
|
the Word modifier) will retrieve the value out of EEPROM and then display the value
|
|
on the screen. See the <a href="READ.htm" target="" title="" alt="" class="MCXref_0" xrefformat="{paratext}">READ</a> and <a href="WRITE.htm" target="" title="" alt="" class="MCXref_0" xrefformat="{paratext}">WRITE</a> commands for more information.</p>
|
|
<p class="PlainText">Finally, a <i>DataItem</i> may be defined using a simple expression with the binary
|
|
operators as shown below:</p><pre class="BScode" xml:space="preserve">
|
|
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
|
|
</pre>
|
|
<div class="Col2">
|
|
<div class="MasterFoot">
|
|
<p MadCap:conditions="BSEconditions.BSEWebHelp (Primary)-INCLUDE"><a href="../../HomeTopics/HomePage.htm">Go to Welcome page</a>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<div class="Col2">
|
|
<div class="MasterFoot">
|
|
<p style="text-align: right;"><span class="ContactInfoProjectName">BASIC Stamp Help</span> <![CDATA[ ]]><span class="ContactInfoVersion#">Version 2.5.4</span> <![CDATA[ ]]></p>
|
|
<p style="text-align: right;">Copyright © <span class="ContactInfoCompanyName">Parallax Inc.</span></p>
|
|
<p style="text-align: right;"><span class="SystemShortDate">8/8/2012</span>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<script type="text/javascript">/* <![CDATA[ */
|
|
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-285614-1']);
|
|
_gaq.push(['_trackPageview']);
|
|
|
|
(function() {
|
|
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
|
|
/* ]]> */</script>
|
|
<script type="text/javascript" src="../../SkinSupport/MadCapBodyEnd.js">
|
|
</script>
|
|
</body>
|
|
</html> |