VarRecall Function (ROM Call 0x85)

vat.h

HSym VarRecall (SYM_STR SymName, unsigned short Flags);

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