NAME

       Blt_TreeGetToken - Grabs a token associated with existing tree data object.

SYNOPSIS

       #include <bltTree.h>

       int
       Blt_TreeGetToken(interp, name, tokenPtr)

ARGUMENTS

       Tcl_Interp   *interp   (in)      Interpreter to report results back to.

       const char   *name     (in)      Name  of  an existing tree data object.  Can be qualified
                                        by a namespace.

       Blt_Tree     *tokenPtr (out)     Points to location to store the client tree token.
_________________________________________________________________

DESCRIPTION

       This procedure obtains a token to a C-based  tree  data  object.   The  arguments  are  as
       follows:

       interp    Interpreter  to report results back to.  If an error occurs, then interp->result
                 will contain an error message.

       name      Name of an existing tree data object.  It's an error  if  a  tree  name  doesn't
                 already  exist.   Name 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.

       tokenPtr  Points  to the location where the returned token is stored. A tree token is used
                 to work with the tree object.

       A token for the tree data object is returned.  Tree  data  objects  can  be  shared.   For
       example, the tree and hiertable 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
       Blt_TreeReleaseToken) the tree data object is automatically destroyed.

RETURNS

       A  standard  Tcl  result  is returned.  If TCL_ERROR is returned, then interp->result will
       contain an error message.  The following errors may occur:

       •  No tree exists as name. You can use  Tcl_TreeExists  to  determine  if  a  tree  exists
          beforehand.

       •  Memory can't be allocated for the token.

EXAMPLE

       The following example allocated a token for an existing tree.

              Blt_Tree token;

              if (Blt_TreeGetToken(interp, "myTree", &token) != TCL_OK) {
                  return TCL_ERROR;
              }
              printf("tree is %s\n", Blt_TreeName(token));

SEE ALSO

       Tcl_TreeCreate, Tcl_TreeExists, Tcl_TreeReleaseToken