SymFind Function (ROM Call 0x60)

vat.h

HSym SymFind (SYM_STR SymName);

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