 |
SymFind |
Function (ROM Call 0x60) |
Finds a symbol.
SymFind searches the variable allocation table (VAT) for a symbol (i.e. variable)
SymName. SymName may also contain a folder name together with
the symbol name (separated by "\"), else only the currently active
folder will be searched. SymFind returns a structure of type HSym,
which contains the handle of the variable table list belonging to the folder
(current, or folder given in the name), and the offset from the beginning of the list to the actual VAT symbol
entry. Use DerefSym to get a pointer to the actual VAT
symbol entry instead. In case of an error (for example, if the symbol does not exist), SymFind
returns HS_NULL. Note that most reserved symbols (i.e. system variables)
are not stored in the VAT table, so you cannot locate them using SymFind.
Note: SymName is not an ordinary C string. Instead, this is a sequence
of characters which starts with the zero character ('\0') and terminates with the zero
character as well, and all TIOS routines for VAT handling need a pointer to the
terminating zero byte as the input argument, which is a little twisty. So, to search for a symbol named
"tetris", instead of
hsym = SymFind ("tetris");
you must do the following:
hsym = SymFind ("\0tetris"+7);
To make this job easier, the macro SYMSTR is implemented,
so you may simply do
hsym = SymFind (SYMSTR ("tetris"));
You may use the older $ macro constructor as well.
Note also that all legal TIOS symbol names must be in lowercase!
Uses: MakeHSym, SymFindPtr
Used by: checkCurrent, EM_moveSymFromExtMem, EM_moveSymToExtMem, EM_twinSymFromExtMem, cmd_blddata, cmd_newdata, cmd_newprob, ERD_process, fopen, de_initRes, de_loop, gr_de_value, gr_execute_seq, gr_seq_value, Regraph, time_loop, ROM Call 0x45E
See also: SymFindMain, SymFindHome, SymFindPtr