Storing And Retrieving Variable Data - Texas Instruments TI-89 Developer's Manual

Chapter 13: Memory Management
push_setfold
TokenizeSymName
VarRecall
VarStore
In order to use most of these routines, the variable names must be tokenized and
pushed onto the estack. TokenizeSymName does this as well as checking for
invalid names. There are only two routines for storing to and retrieving variable
values: VarStore and VarRecall. This is because there are many system
variables that are not in the symbol table (system variables are only accessible
through VarStore and VarRecall). VarStore also does extensive type checking
to protect certain variable types. For example, it is illegal to copy anything but a
program to another program or a data variable to another data variable.
VarStore must also insure that certain system variables are only stored to in the
proper mode. As an example, tmin which is used in parametric graphing, can
only be stored to in parametric graph mode and it has a limited range of values
that can be stored to it. VarStore does all of the necessary type and value
checking for all variables. To reiterate, the low-level routines do no type or value
checking and should be used with extreme caution.
Note: Routines that take a variable number of arguments (cmd_delvar, cmd_delfold,
13.3.2.

Storing and Retrieving Variable Data

As noted earlier, the file system is the preferred method for an app to store or
retrieve data. VarStore is the routine to store to a variable, and VarRecall is the
routine to access a variable. These routines are complicated because of the
built-in graphing application and the restrictions on the predefined system
variables. When a variable is accessed while graphing or building a table, a flag
in the symbol table entry for that variable is set. Whenever a store (or any
change, including delete, rename, etc.) is done to a variable that already exists,
the flags (one for each of the two possible graphs) must be checked to know if
the graph and table are now incorrect because the variable changed. Other
actions can also cause the graph or table to be incorrect — for example,
changing the angle mode or folder.
It is even more important to use VarRecall and VarStore for system variables,
some of which are not in the symbol table. In addition to the graph reference
flags, the type or range of a value must be checked before storing to some of the
system variables, and storing to some of them causes other system
TI-89 / TI-92 Plus Developer Guide
— Set current default folder (TI-BASIC version of FolderCur).
— Tokenize a name and check for invalid or reserved names.
— Look-up a variable (returning its HSYM).
— Store a value to a variable.
cmd_lock, cmd_unlock, cmd_archive, cmd_unarchiv) require an END_TAG on the
estack to mark the end of the parameter list of variable names passed to them.
Not for Distribution
137
Beta Version January 26, 2001