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

[ROM Call]
Index=$283

[Description]
Finds a symbol and returns a pointer to the VAT entry.

[Explanation]
SymFindPtr acts like <A HREF="$$LINK(SymFind)">SymFind</A> and related
functions, but instead of a <A HREF="$$LINK(HSym)">HSym</A>
structure, it returns a pointer to the actual VAT entry. SymFindPtr returns
<A HREF="$$LINK(alloc.h/NULL)">NULL</A> in case of an error.
So, it acts somewhat as a combination of
<A HREF="$$LINK(SymFind)">SymFind</A> and
<A HREF="$$LINK(DerefSym)">DerefSym</A>.
<BR><BR>
<I>Flags</I> is an additional argument which determines the searching method.
It is a set of binary flags. The exact meaning of these flags are still
unknown for me, but at the moment, I know the following for sure:
<UL>
<LI>If <I>Flags</I>&nbsp;=&nbsp;0, the search is performed like using the
<A HREF="$$LINK(SymFind)">SymFind</A> function (i.e. through current or given
folder);</LI>
<LI>If <I>Flags</I>&nbsp;=&nbsp;4, the search is performed like using the
<A HREF="$$LINK(SymFindMain)">SymFindMain</A> function (i.e. through main
folder only).</LI>
</UL>
What I also know is that if b15 in <I>Flags</I> is set, the search is
somewhat related to the folder list, and it is possible to search for folders
as well. But I still can't conclude the <U>exact</U> meaning of these flags.
So, instead of giving uncertain information, I will stop here. Everything
about this function presented so far is certainly true. Fortunately, the TIOS
set of VAT functions is rich enough so that eventual additional possibilities
of this function may be simulated using other known functions. Any additional
information will be welcomed, if someone knows more than me.
<BR><BR>
As an example of usage, this is a legal method how to lock a variable named
"tetris":
<PRE>SymFindPtr(SYMSTR("tetris"),0)-&gt;flags.bits.locked = 1;
</PRE>
See <A HREF="$$LINK(SYMSTR)">SYMSTR</A> for info about symbol names.

[References]
In=SymAddTwin, SymDel, SymFind, SymFindMain, SymMove, VarRecall, VarStore, unknown.h/GraphOrTableCmd, unknown.h/_ROM_CALL_439
Out=CheckSysFunc, FolderAdd, SymCmp, dialogs.h/DlgMessage, system.h/XR_stringPtr, unknown.h/ParseSymName, unknown.h/_mu16u16
Out_EV_eventLoop=1
