[Main]
Name=SymFind
Type=Function
Subtype=ROM Call
Header Files=vat.h
Definition=HSym SymFind (SYM_STR SymName);
See Also=SymFindMain, SymFindHome, SymFindPtr

[ROM Call]
Index=$60

[Description]
Finds a symbol.

[Explanation]
SymFind searches the variable allocation table (VAT) for a symbol (i.e. variable)
<I>SymName</I>. <I>SymName</I> 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 <A HREF="$$LINK(HSym)">HSym</A>,
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 <A HREF="$$LINK(DerefSym)">DerefSym</A> 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 <A HREF="$$LINK(HS_NULL)">HS_NULL</A>. Note that most reserved symbols (i.e. system variables)
are not stored in the VAT table, so you cannot locate them using SymFind.
<BR><BR>
<B>Note:</B> <I>SymName</I> 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
<I>terminating</I> zero byte as the input argument, which is a little twisty. So, to search for a symbol named
"tetris", instead of
<PRE>hsym = SymFind ("tetris");
</PRE>
you must do the following:
<PRE>hsym = SymFind ("\0tetris"+7);
</PRE>
To make this job easier, the macro <A HREF="$$LINK(SYMSTR)">SYMSTR</A> is implemented,
so you may simply do
<PRE>hsym = SymFind (SYMSTR ("tetris"));
</PRE>
You may use the older <A HREF="$$LINK(dollar)">$</A> macro constructor as well.
<BR><BR>
Note also that all legal TIOS symbol names must be in lowercase!

[References]
In=checkCurrent, EM_moveSymFromExtMem, EM_moveSymToExtMem, EM_twinSymFromExtMem, bascmd.h/cmd_blddata, bascmd.h/cmd_newdata, bascmd.h/cmd_newprob, error.h/ERD_process, stdio.h/fopen, unknown.h/de_initRes, unknown.h/de_loop, unknown.h/gr_de_value, unknown.h/gr_execute_seq, unknown.h/gr_seq_value, unknown.h/Regraph, unknown.h/time_loop, unknown.h/_ROM_CALL_45E
Out=MakeHSym, SymFindPtr
Out_EV_eventLoop=1
