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  com-
                                           mand.   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  contain-
                                           ing  a  command string
                                           (or sequence  of  com-
                                           mands  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  exe-
       cuted,  its  commands  are compiled into bytecode instruc-
       tions 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 dur-
       ing 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  com-
       mand ``uplevel 0''.

       During the processing of a Tcl command it is legal to make
       nested calls to evaluate other commands (this is how  pro-
       cedures  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 mes-
       sage indicating that the return, break, or  continue  com-
       mand  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