ZBasic Language Reference
46
ZBasic Microcontrollers
2.9 Persistent Variables
You may define variables that are stored in the processor’s internal EEPROM, referred to in this
document as Persistent Memory. It is called persistent because the values that you store there are
retained even if the system is powered down or reset. This characteristic makes persistent variables
useful for storing configuration information for your application and other similar information that your
application needs to be preserved.
A persistent variable is defined at the module level using the syntax:
{Public | Private | Dim} <name> as Persistent <type>
Using the keyword Dim has the same effect as using Private. Within a subroutine or function, a
persistent variable is defined using the syntax.
Dim <name> as Persistent <type>
In both cases, the <type> element may be any numeric type (e.g. Byte, Integral, Single, etc.), Boolean or
a user-defined type (structure or enumeration). A persistent string must be defined using the bounded
string syntax (Section 2.11.1), i.e.
Dim <name> as Persistent BoundedString(<size-expr>)
The <size-expr> element must be a constant integral expression that specifies the number of bytes to
reserve for the persistent string’s characters.
Examples
Dim kbdAttached as Persistent Boolean
Private signOnMsg as Persistent BoundedString(25)
It is important to note that the implementation of the PersistentString type is identical to that of the
BoundedString type and is therefore not protected from overwriting the boundaries of the data item. To
protect against overwriting, it is advisable to explicitly limit the size of the string to be written.
Arrays of persistent variables may be defined as well. To do so, simply add the array dimension list to the
variable name in the same manner as for regular variables. If no lower bound is specified, the default
array base applies.
Example
Dim freq(1 to 10) as PersistentInteger
It is important to note that persistent variables are not initialized by the system. They have values based
on whatever data happens to be at the Persistent Memory address to which they are assigned. The
compiler assigns Persistent Memory addresses in the order that modules are compiled and, within
modules, in the order the variables are defined.
To avoid problems of unexpected address order changes, it is highly recommended that all persistent
variables be defined in a single module. Also, it is recommended when you add more persistent variables
to an existing application that you add them following the definitions of the previously existing persistent
variables. Deleting persistent variables or inserting new persistent variables in the midst of existing ones
may cause problems because it will change the address to which subsequent variables are assigned.
You’ll probably want to build into your application a way to initialize all of your persistent variables to a
known state. This initialization only needs to be done once, when the application is first installed (the
FirstTime() function may be useful for this purpose). It may also be useful, however, to be able to do
this at other times as well. Another useful technique is to include a persistent variable whose only
purpose is to indicate that the persistent variables have been properly initialized. For this to work, you
would need to choose a value that is unlikely to otherwise occur. It may even be advisable to place such
 |
 |
 |