'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" SCCS: @(#) EvalObj.3 1.4 97/01/22 15:18:44
'\" 
.so man.macros
.TH Tcl_EvalObj 3 8.0 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_EvalObj, Tcl_GlobalEvalObj \- execute Tcl commands
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_EvalObj\fR(\fIinterp, objPtr\fR)
.sp
int
\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR)
.SH ARGUMENTS
.AS Tcl_Interp **termPtr;
.AP Tcl_Interp *interp in
Interpreter in which to execute the command.
The command's result will be stored in the interpreter's result object
and can be retrieved using \fBTcl_GetObjResult\fR.
.AP Tcl_Obj *objPtr in
A Tcl object containing a command string
(or sequence of commands in a string) to execute.
.BE

.SH DESCRIPTION
.PP
These two procedures execute Tcl commands.
\fBTcl_EvalObj\fR is the core procedure
and is used by \fBTcl_GlobalEvalObj\fR.
It executes the commands in the script held by \fIobjPtr\fR
until either an error occurs or it reaches the end of the script.
If this is the first time \fIobjPtr\fR has been executed,
its commands are compiled into bytecode instructions
that are then executed if there are no compilation errors.
.PP
The return value from \fBTcl_EvalObj\fR is one of the Tcl return codes
\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
\fBTCL_CONTINUE\fR,
and a result object containing additional information
(a result value or error message)
that can be retrieved using \fBTcl_GetObjResult\fR.
If an error occurs during compilation, this return information
describes the error.
Otherwise, this return information corresponds to the last command
executed from \fIobjPtr\fR.
.PP
\fBTcl_GlobalEvalObj\fR is similar to \fBTcl_EvalObj\fR except that it
processes the command at global level.
This means that the variable context for the command consists of
global variables only (it ignores any Tcl procedure that is active).
This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
.PP
During the processing of a Tcl command it is legal to make nested
calls to evaluate other commands (this is how procedures and
some control structures are implemented).
If a code other than \fBTCL_OK\fR is returned
from a nested \fBTcl_EvalObj\fR invocation,
then the caller should normally return immediately,
passing that same return code back to its caller,
and so on until the top-level application is reached.
A few commands, like \fBfor\fR, will check for certain
return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
specially without returning.
.PP
\fBTcl_EvalObj\fR keeps track of how many nested \fBTcl_EvalObj\fR
invocations are in progress for \fIinterp\fR.
If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
about to be returned from the topmost \fBTcl_EvalObj\fR
invocation for \fIinterp\fR,
it converts the return code to \fBTCL_ERROR\fR
and sets the interpreter's result object
to point to an error message indicating that
the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
invoked in an inappropriate place.
This means that top-level applications should never see a return code
from \fBTcl_EvalObj\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.

.SH "SEE ALSO"
Tcl_GetObjResult, Tcl_SetObjResult

.SH KEYWORDS
command, execute, file, global, object, object result, variable