Man Linux: Main Page and Category List

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