 |
VarRecall |
Function (ROM Call 0x85) |
A higher-level variant of SymFind.
VarRecall works like SymFind, but it is able to handle system variables which
do not have an entry in the variable allocation table. SymName is a pointer to the
terminating zero byte of the VAT variable name (see SYMSTR for more info
about symbol names). Flags is a collection of flags defined in the
enum VarRecallFlags:
VR_NO_SYS_VARS |
Do not return system variables. |
VR_FUNC_NAME |
Accept strings terminating with an opening parenthesis (like "y1(") for SymName. |
VR_LINK |
Used only internally by the link code. |
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 recall the
system variable called "xmin", you have to use the following code:
hsym = VarRecall ((const ESQ []){XMIN_TAG, EXT_SYSTEM_TAG} + 1, 0);
You may use the TokenizeSymName
function if you need a generic way to access variables, like this:
TokenizeSymName ("xmin", TSF_ALLOW_RESERVED);
hsym = VarRecall (top_estack, 0);
To make the handling of system variables consistent with normal variables
even though system variables do not have an entry in the variable allocation
table, VarRecall returns a reference to a dummy SYM_ENTRY if a system
variable is requested. It actually copies the contents of the system variable
into an internal buffer and adds the appropriate tag. Since one dummy entry
is used for many system variables, you have to store the contents of each
variable in your program if you need to access more than one value at a time.
In other words, a dummy HSym descriptor which is created for system variabes
is shared by all variables not in the VAT. Thus the next call to VarRecall
for such a variable will return the same descriptor, but with a different
value (and the previous descriptor will be invalid). So if VarRecall is used
for system variables, it is best to keep a copy of the value pointed to by
the HSym if it is needed.
It might be useful to know (but it is not reliable) that internally, the
folder field of the returned HSym contains a handle to the following type of
structure:
struct SysVarSym {
unsigned short DataSize;
ESQ Data[60];
SYM_ENTRY sysVar;
SYM_ENTRY tblInput;
SYM_ENTRY unit;
};
The offset field is then either 62 for system variables (offset to the sysVar
field), 76 for the "tblInput" variable (offset to the tblInput field), or 90
for units (offset to the unit field). The reason that three different
SYM_ENTRY type fields are used is that they contain different flags and
handles. sysVar and unit both contain the same handle as the folder field of
the HSym, whereas tblInput contains a handle to an external memory location.
The compatibility flag is CF_NONE for system variables (including "tblInput"),
but CF_NEW for units. All three fields contain the SF_LOCKED flag.
If the SYM_ENTRY structures use the same handle
as the folder field of the HSym returned by VarRecall,
they use in fact the first 62 bytes of this internal structure. This saves a
handle in the operating system.
When dealing with system variables and units, it is not reliable to use the
name field of the SYM_ENTRY structure
whose address is obtained with DerefSym
(which is, of course, one of the three structures mentioned above). It is
blank for all system variables and units except "tblInput".
Note: This function may throw different errors. Especially, most system
variables cannot be used in a function that is being graphed, either because
they change too often or because they are used by the graph routines
themselves (for example, "xmin" or "xc"). If these variables are accessed
while graphing, VarRecall throws an error. However, locked variables may be
looked up with VarRecall.
Uses: CheckSysFunc, DerefSym, FindSymInFolder, IsMainFolderStr, MakeHSym, SymFindPtr, TempFolderName, RemainingArgCnt, HToESI, next_expression_index, push_expression, push_Float, push_quantum, top_estack, gr_active, gr_flags, memcpy, strcmp, XR_stringPtr, is_transfinite, round14, CTypeTable, EV_currentApp, gr_find_de_result, gr_find_func_index, ParseSymName, ROM Call 0x46B
Used by: cmd_andpic, cmd_archive, cmd_custom, cmd_cyclepic, cmd_delvar, cmd_dialog, cmd_fill, cmd_get, cmd_lock, cmd_movevar, cmd_passerr, cmd_popup, cmd_rclgdb, cmd_rclpic, cmd_request, cmd_rplcpic, cmd_showstat, cmd_sinreg, cmd_sorta, cmd_sortd, cmd_toolbar, cmd_unarchiv, cmd_unlock, cmd_xorpic, push_csolve, push_czeros, push_gettype, push_max, push_min, push_nsolve, push_randpoly, push_solve, push_zeros, VarOpen, push_internal_simplify, handleRclKey, handleVarLinkKey, FDelete, FOpen, OSLinkCmd, sendcalc, delete_list_element, did_push_approx_inflection_point, did_push_var_val, does_push_fetch, GetStatValue, push_simplify, push_user_func, ROM Call 0x437, ROM Call 0x438, ROM Call 0x468, ROM Call 0x4D1