'\"
'\" Copyright 1991-1998 by Bell Labs Innovations for Lucent Technologies.
'\"
'\" Permission to use, copy, modify, and distribute this software and its
'\" documentation for any purpose and without fee is hereby granted, provided
'\" that the above copyright notice appear in all copies and that both that the
'\" copyright notice and warranty disclaimer appear in supporting documentation,
'\" and that the names of Lucent Technologies any of their entities not be used
'\" in advertising or publicity pertaining to distribution of the software
'\" without specific, written prior permission.
'\"
'\" Lucent Technologies disclaims all warranties with regard to this software,
'\" including all implied warranties of merchantability and fitness.  In no event
'\" shall Lucent Technologies be liable for any special, indirect or
'\" consequential damages or any damages whatsoever resulting from loss of use,
'\" data or profits, whether in an action of contract, negligence or other
'\" tortuous action, arising out of or in connection with the use or performance
'\" of this software.  
'\"
'\"
.so man.macros
.TH Blt_TreeGetToken 3 BLT_VERSION BLT "BLT Library Procedures"
.BS
.SH NAME
Blt_TreeGetToken \- Grabs a token associated with existing tree data object.
.SH SYNOPSIS
.nf
\fB#include <bltTree.h>\fR
.sp
int 
\fBBlt_TreeGetToken\fR(\fIinterp\fR, \fIname\fR, \fItokenPtr\fR)
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Interpreter to report results back to.  
.AP "const char" *name  in
Name of an existing tree data object.  Can be qualified by a namespace.
.AP Blt_Tree *tokenPtr out
Points to location to store the client tree token.
.BE
.SH DESCRIPTION
.PP
This procedure obtains a token to a C-based tree data object.  The
arguments are as follows:
.TP 1i
\fIinterp\fR
Interpreter to report results back to.  If an error occurs, then
interp->result will contain an error message.
.TP 1i
\fIname\fR
Name of an existing tree data object.  It's an error if a tree
\fIname\fR doesn't already exist.  \fIName\fR can be qualified by 
a namespace such as \f(CWfred::myTree\fR.  If no namespace qualifier 
is used, the tree the current namespace is searched, then the global
namespace. 
.TP 1i
\fItokenPtr\fR
Points to the location where the returned token is stored. A tree
token is used to work with the tree object.  
.PP
A token for the tree data object is returned.  Tree data objects can
be shared.  For example, the \fBtree\fR and \fBhiertable\fR 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
\fBBlt_TreeReleaseToken\fR) the tree data object is automatically
destroyed.
.PP
.SH RETURNS
A standard Tcl result is returned.  If TCL_ERROR is returned, then
\fIinterp->result\fR will contain an error message.  The following errors
may occur:
.IP \(bu 3
No tree exists as \fIname\fR. You can use \fBTcl_TreeExists\fR to
determine if a tree exists beforehand.
.IP \(bu
Memory can't be allocated for the token.
.SH EXAMPLE
The following example allocated a token for an existing tree.
.CS
Blt_Tree token;

if (Blt_TreeGetToken(interp, "myTree", &token) != TCL_OK) {
    return TCL_ERROR;
}
printf("tree is %s\\n", Blt_TreeName(token));
.CE
.SH SEE ALSO
Tcl_TreeCreate, Tcl_TreeExists, Tcl_TreeReleaseToken