[Main]
Name=HomeStorePair
Type=Function
Subtype=tigcc.a
Header Files=homescr.h
Definition=void HomeStorePair (HANDLE Entry, HANDLE Ans);
See Also=HomeStore, HS_pushEmptyFIFONode

[Description]
Creates a new history pair with given contents.

[Explanation]
HomeStorePair creates a new Home Screen history pair with a given entry and
answer part. <I>Entry</I> and <I>Ans</I> have to point to multi-expressions
(see <A HREF="$$LINK(estack.h/MULTI_EXPR)">MULTI_EXPR</A>). They may be the
same handles; in this case, the same expression will be used on both sides
of the screen.
<BR><BR>
HomeStorePair first uses <A HREF="$$LINK(HS_newFIFONode)">HS_newFIFONode</A>
to allocate memory for a new FIFO node, then fills the <I>Expr</I> fields
of the entry and answer elements with <I>Entry</I> and <I>Ans</I>, and then
calls <A HREF="$$LINK(HS_pushEmptyFIFONode)">HS_pushEmptyFIFONode</A>. If
<A HREF="$$LINK(HS_pushEmptyFIFONode)">HS_pushEmptyFIFONode</A> throws an
error, it calls <A HREF="$$LINK(HS_freeFIFONode)">HS_freeFIFONode</A> to free
all handles, even <I>Entry</I> and <I>Ans</I>.
<BR><BR>
In any case, the expressions pointed to by <I>Entry</I> and <I>Ans</I> should
not be modified after calling this function. In fact, the two handles then
belong to the operating system, and should not be used any more.
<BR><BR>
<B>Note:</B> It seems that the handles <I>Entry</I> and <I>Ans</I> should be
allocated with <A HREF="$$LINK(alloc.h/HeapAlloc)">HeapAlloc</A> (or
<A HREF="$$LINK(alloc.h/HeapAllocThrow)">HeapAllocThrow</A>), and should not
be locked. Be sure to read the notes about
<A HREF="$$LINK(HS_pushEmptyFIFONode)">HS_pushEmptyFIFONode</A> as well.

[References]
Out=HS_newFIFONode, HS_freeFIFONode, HS_pushEmptyFIFONode, alloc.h/HeapDeref, alloc.h/HeapFree, error.h/ER_catch, error.h/ER_success, error.h/ER_throwVar
