man EvalObj () - execute Tcl commands
NAME
Tcl_EvalObj, Tcl_GlobalEvalObj - execute Tcl commands
SYNOPSIS
#include <tcl.h> int Tcl_EvalObj(interp, objPtr) int Tcl_GlobalEvalObj(interp, objPtr)
ARGUMENTS
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. 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 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