<!-- manual page source format generated by PolyglotMan v3.0.9, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
<HTML>
<HEAD>
<TITLE>Blt_TreeGetToken(3) manual page</TITLE>
</HEAD>
<BODY bgcolor=white>
<A HREF="#toc">Table of Contents</A><P>
<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
Blt_TreeGetToken - Grabs a token
associated with existing tree data object.
<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
<BR>
<PRE>#include <bltTree.h>
int
Blt_TreeGetToken(interp, name, tokenPtr)
</PRE>
<H2><A NAME="sect2" HREF="#toc2">Arguments</A></H2>
<P>
Tcl_Interp <I>*interp</I><tt> </tt> <tt> </tt> (in)<BR>
<tt> </tt> <tt> </tt> Interpreter to report results back to. <P>
const char <I>*name</I><tt> </tt> <tt> </tt> (in)<BR>
<tt> </tt> <tt> </tt> Name of an existing tree data object. Can be qualified by a namespace. <P>
Blt_Tree
<I>*tokenPtr</I><tt> </tt> <tt> </tt> (out)<BR>
<tt> </tt> <tt> </tt> Points to location to store the client tree token.
<H2><A NAME="sect3" HREF="#toc3">Description</A></H2>
<P>
This procedure
obtains a token to a C-based tree data object. The arguments are as follows:
<DL>
<DT><I>interp</I> </DT>
<DD>Interpreter to report results back to. If an error occurs, then
interp->result will contain an error message. </DD>
<DT><I>name</I> </DT>
<DD>Name of an existing tree
data object. It's an error if a tree <I>name</I> doesn't already exist. <I>Name</I> can
be qualified by a namespace such as fred::myTree. If no namespace qualifier
is used, the tree the current namespace is searched, then the global namespace.
</DD>
<DT><I>tokenPtr</I> </DT>
<DD>Points to the location where the returned token is stored. A tree
token is used to work with the tree object. </DD>
</DL>
<P>
A token for the tree data
object is returned. Tree data objects can be shared. For example, the <B>tree</B>
and <B>hiertable</B> commands may be accessing the same tree data object. Each
client grabs a token that is associated with the tree. When all tokens
are released (see <B>Blt_TreeReleaseToken</B>) the tree data object is automatically
destroyed. <P>
<H2><A NAME="sect4" HREF="#toc4">Returns</A></H2>
A standard Tcl result is returned. If TCL_ERROR is returned,
then <I>interp->result</I> will contain an error message. The following errors may
occur:
<UL>
<LI>No tree exists as <I>name</I>. You can use <B>Tcl_TreeExists</B> to determine if
a tree exists beforehand. </LI><LI>Memory can't be allocated for the token. </LI>
</UL>
<H2><A NAME="sect5" HREF="#toc5">Example</A></H2>
The
following example allocated a token for an existing tree. <BR>
<CODE>Blt_Tree token;<BR>
<P>
if (Blt_TreeGetToken(interp, "myTree", &token) != TCL_OK) {<BR>
return TCL_ERROR;<BR>
}<BR>
printf("tree is %s\n", Blt_TreeName(token));<BR>
<H2><A NAME="sect6" HREF="#toc6"></CODE>See Also</A></H2>
Tcl_TreeCreate, Tcl_TreeExists, Tcl_TreeReleaseToken <P>
<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Arguments</A></LI>
<LI><A NAME="toc3" HREF="#sect3">Description</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Returns</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Example</A></LI>
<LI><A NAME="toc6" HREF="#sect6">See Also</A></LI>
</UL>
</BODY></HTML>
