NAME

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

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

• 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

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

SEE ALSO