[Main]
Name=SymAddTwin
Type=Function
Subtype=ROM Call
Header Files=vat.h
Definition=HSym SymAddTwin (SYM_STR SymName);

[ROM Call]
Index=$27F

[Description]
Creates a twin symbol.

[Explanation]
SymAddTwin creates a twin entry in the variable allocation table (VAT) for an
existing symbol <I>SymName</I>. A twin symbol is, in fact, another entry in the VAT
with the same variable name, but with a different handle. The TIOS creates twin symbols
during execution of archived programs, just in front of the normal symbol in the VAT table
(see <A HREF="$$LINK(vat.h/EM_twinSymFromExtMem)">EM_twinSymFromExtMem</A>).
A twin symbol is "stronger" that a normal symbol, i.e. existence of a twin symbol temporary hides the symbol with the same
name, until the twin symbol is deleted. Twin symbols have the "twin" bit set in the VAT
entry (see <A HREF="$$LINK(vat.h/SYM_ENTRY)">SYM_ENTRY</A> for the structure of a VAT entry), but in
the VAR-LINK menu, it is shown as "archived". SymAddTwin returns the same result as
<A HREF="$$LINK(vat.h/SymAdd)">SymAdd</A> (<A HREF="$$LINK(vat.h/HS_NULL)">HS_NULL</A> in case of an error). If the symbol <I>SymName</I>
does not exist, this is also an error.

[References]
In=vat.h/EM_twinSymFromExtMem
Out=vat.h/MakeHSym, vat.h/SymCpy, vat.h/SymFindPtr, alloc.h/HeapRealloc, mem.h/memmove, unknown.h/_ds32s32
Out_EV_eventLoop=1
