Tcl_EvalObj(3) Tcl (8.0) Tcl_EvalObj(3)
_________________________________________________________________
NAME
Tcl_EvalObj, Tcl_GlobalEvalObj - execute Tcl commands
SYNOPSIS
#include <tcl.h>
int
Tcl_EvalObj(interp, objPtr)
int
Tcl_GlobalEvalObj(interp, objPtr)
ARGUMENTS
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
Tcl_GetObjResult.
Tcl_Obj *objPtr (in) A Tcl object containing
a command string (or
sequence of commands in
a string) to execute.
_________________________________________________________________
DESCRIPTION
These two procedures execute Tcl commands. Tcl_EvalObj is
the core procedure and is used by Tcl_GlobalEvalObj. It
executes the commands in the script held by objPtr until
either an error occurs or it reaches the end of the script.
If this is the first time objPtr has been executed, its
commands are compiled into bytecode instructions that are
then executed if there are no compilation errors.
The return value from Tcl_EvalObj is one of the Tcl return
codes TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or
TCL_CONTINUE, and a result object containing additional
information (a result value or error message) that can be
retrieved using Tcl_GetObjResult. If an error occurs during
compilation, this return information describes the error.
Otherwise, this return information corresponds to the last
command executed from objPtr.
Tcl_GlobalEvalObj is similar to Tcl_EvalObj except that it
processes the command at global level. This means that the
variable context for the command consists of global
Page 1 (printed 2/19/99)
Tcl_EvalObj(3) Tcl (8.0) Tcl_EvalObj(3)
variables only (it ignores any Tcl procedure that is
active). This produces an effect similar to the Tcl command
``uplevel 0''.
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 TCL_OK is returned from a nested
Tcl_EvalObj 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 for, will check for certain
return codes, like TCL_BREAK and TCL_CONTINUE, and process
them specially without returning.
Tcl_EvalObj keeps track of how many nested Tcl_EvalObj
invocations are in progress for interp. If a code of
TCL_RETURN, TCL_BREAK, or TCL_CONTINUE is about to be
returned from the topmost Tcl_EvalObj invocation for interp,
it converts the return code to TCL_ERROR and sets the
interpreter's result object to point to an error message
indicating that the return, break, or continue command was
invoked in an inappropriate place. This means that top-
level applications should never see a return code from
Tcl_EvalObj other then TCL_OK or TCL_ERROR.
SEE ALSO
Tcl_GetObjResult, Tcl_SetObjResult
KEYWORDS
command, execute, file, global, object, object result,
variable
Page 2 (printed 2/19/99)