 |
VarStore |
Function (ROM Call 0x86) |
High-level function to store values into variables.
VarStore performs many storing operations, from basic file saving to
list/matrix element access. Although some of its operations appear to be
quite trivial, it provides a consistent interface to all storing operations,
even for system variables. So, this is the general system routine for storing
to TI-Basic variables.
VarStore can perform different types of operations. It can store values into
TI-Basic variables (it will create a new VAT entry if needed), prepare
variables to be stored to, or store individual values to elements of a list
or matrix. The data type and domain of system variables are verified to be
correct.
SymName is the symbol name of the variable in which the value will be stored
(see SYMSTR for more info about symbol names). VarStore returns the HSym
descriptor of the TI-Basic variable, or HS_NULL if the variable is a system
variable (which is not stored in the VAT).
Note that you cannot create the necessary token for system variables with the
SYMSTR or $ macro.
Instead, system variables have their own tags. For example, to store something in the
system variable xmin
, you have to use the following code:
VarStore ((const ESQ []){XMIN_TAG, EXT_SYSTEM_TAG} + 1, ...);
You may use the TokenizeSymName
function if you need a generic way to access variables.
The parameter Flags determines the meaning of the remaining parameters:
STOF_ESI |
An extra parameter of type ESI is needed, which points to an
expression which will be stored into the variable. Basically, this parameter may point to an
arbitrary locked block of memory, not necessarily on the expression stack.
On a side note, this variant is used internally if RETURN_VALUE <variable>
is defined. |
STOF_HESI |
Like STOF_ESI, but the extra parameter has the type
HANDLE. It must be a handle
to a block of memory containing the data to be stored. The handle will be
locked during the operation. |
STOF_ELEMENT |
Three extra parameters are needed. The first extra parameter has the type
ESI; it should point to an expression
which will be stored into an element of a list or matrix variable determined
by the SymName parameter. The second and third parameters have the type unsigned short .
For matrices, they determine the column and the row of the element, respectively.
For lists, the second extra parameter is the index and the third parameter must
be zero. Indices for both matrices and lists start at one. |
STOF_NONE |
Nothing is assumed about the source, so no copying is done (it is left
to the caller). Only the VAT entry will be created. The name and flags
and other conditions will be verified. |
Additionally, the parameter Flags may contain some tag values (see
Tags for more info). The allowed tags are
USERFUNC_TAG (in this case an extra parameter
of type ESI should point to the user function
which will be stored; note that this is not FUNC_TAG),
TEXT_TAG (for text variables),
GDB_TAG (for Graph Database variables),
PIC_TAG (for picture variables),
DATA_TAG (for data variables), and
OTH_TAG (for custom type variables).
In all of these cases except USERFUNC_TAG,
the destination is verified to have the same type as the source, but the copy
operation is not done. There are more possible values for Flags, but
they are used only for internal purposes in the TIOS.
The parameter Size is the size of the source data including the tag
but not the size word stored in the heap. If Size is zero, then the
size of the expression pointed to by the first extra parameter will be used
(this is allowed if Flags is
STOF_ESI,
STOF_HESI, or
STOF_ELEMENT).
Otherwise, the new variable is not allocated, but the folder field in
the returned HSym descriptor may still not be
H_NULL if previous data existed in that
variable).
Note: VarStore may throw various errors, and may cause heap compression (garbage
collection). For example, some VAT variables are system protected (see
QSysProtected). These include
programs and functions (TI-Basic or ASM), data variables, graph databases,
custom type files, pictures, and text variables. Only variables of the same
type can be copied to a system-protected variable. If the variable name
already exists, the lock flag is checked (a variable that is locked or
archived cannot be overwritten; VarStore throws an error in this case). System
variables cannot be locked and some system variables cannot be changed by the
user. VarStore also checks the SF_HIDDEN flag
in the VAT entry (see the SYM_ENTRY structure for more info),
which is actually an "in-use" flag. Any variable being used by an application
cannot be overwritten except by that application (it cannot be deleted,
renamed, or linked, either). The in-use count is verified to be 0 for functions
and programs.
If the variable is not a system variable, locked, system protected,
or in use, a value can be stored to it no matter what it contained before.
However, there are type restrictions on individual elements of lists or
matrices. Usually, VarStore makes sure there is enough memory left to store
the new contents to the variable before deleting the current contents of the
variable. When storing to an existing variable, both graph reference flags are
tested (SF_GREF1 and SF_GREF2).
If one or both is set, the corresponding dirty graph and dirty table flag(s)
are set to indicate the graph and table are no longer valid. Storing to an
individual element or submatrix of a matrix or list does the same checks as
for an existing variable, and updates the length. In addition, the data type
of the element needs to be correct (expression, relation, string).
Only functions with the correct function arguments can be stored in the
variables reserved as system functions. These are y1(x)...y99(x)
,
xt1(t)...xt99(t)
, yt1(t)...yt99(t)
, r1(q)...r99(q)
, u1(n)...u99(n)
,
y1'(t)...y99'(t)
, and z1(x,y)...z99(x,y)
.
They can be single-line or multi-line functions, but an error is returned if
the user tries to create any other data type with those names or if the
number of arguments is incorrect. Since they are system functions, they
cannot be locked and must be in the main folder. Empty functions are not
valid and should not be added to the symbol table.
This is true for user functions as well.
Uses: CheckSysFunc, DerefSym, IsMainFolderStr, MakeHSym, QSysProtected, SymAddMain, SymDel, SymFindMain, SymFindPtr, HeapAlloc, HeapFree, HeapLock, HeapRealloc, ER_throwVar, HToESI, next_expression_index, gr_active, gr_flags, gr_other, memcpy, memmove, strcmp, NeedStack, XR_stringPtr, round12_err, ck_valid_float, CTypeTable, EV_currentApp, ForceFloat, gen_version, GetSysGraphRef, OO_GetAppAttr, ParseSymName, primary_tag_list, statFree, _bcd_math, ROM Call 0x3E8, ROM Call 0x439, ROM Call 0x46B, ROM Call 0x5C5
Used by: EX_stoBCD, SetOK, cmd_blddata, cmd_clrerr, cmd_dialog, cmd_endtry, cmd_fill, cmd_get, cmd_input, cmd_inputstr, cmd_newdata, cmd_newpic, cmd_popup, cmd_prompt, cmd_request, cmd_sinreg, cmd_sorta, cmd_sortd, cmd_stogdb, cmd_try, VarNew, VarSaveAs, EV_defaultHandler, FOpen, gdb_recall, assign_between, de_initRes, de_loop, delete_list_element, gr_stopic, InitDEMem, InitTimeSeq, push_user_func, recall_data_var, spike_in_editor, spike_titles_in_editor, store_data_var, store_func_def, store_to_subscripted_element, ValidateStore, VarStoreLink, ROM Call 0x438