VarStore Function (ROM Call 0x86)

vat.h

HSym VarStore (SYM_STR SymName, unsigned short Flags, unsigned short Size, ...);

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