NAME

       Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval - exe-
       cute Tcl commands

SYNOPSIS

       #include <tcl.h>

       int
       Tcl_Eval(interp, cmd)

       int
       Tcl_VarEval(interp, string, string, ... (char *) NULL)

       int
       Tcl_EvalFile(interp, fileName)

       int
       Tcl_GlobalEval(interp, cmd)

ARGUMENTS

       Tcl_Interp   *interp      (in)      Interpreter  in  which
                                           to  execute  the  com-
                                           mand.   String  result
                                           will   be   stored  in
                                           interp->result.

       char         *cmd         (in)      Command  (or  sequence
                                           of  commands)  to exe-
                                           cute.   Must   be   in
                                           writable        memory
                                           (Tcl_Eval makes tempo-
                                           rary  modifications to
                                           the command).

       char         *string      (in)      String forming part of
                                           Tcl command.

       char         *fileName    (in)      Name  of file contain-
                                           ing    Tcl     command
                                           string.
_________________________________________________________________

DESCRIPTION

       All   four  of  these  procedures  execute  Tcl  commands.
       Tcl_Eval is the core procedure:  it parses  commands  from
       cmd  and  executes  them  in  order  until either an error
       occurs or it reaches the end of the  string.   The  return
       value from Tcl_Eval is one of the Tcl return codes TCL_OK,
       TCL_ERROR, TCL_RETURN,  TCL_BREAK,  or  TCL_CONTINUE,  and
       interp->result  will  point  to  a  string with additional
       cmd.

       Tcl_VarEval takes any number of string  arguments  of  any
       length, concatenates them into a single string, then calls
       Tcl_Eval to execute that string  as  a  Tcl  command.   It
       returns  the  result  of  the  command  and  also modifies
       interp->result in the usual fashion for Tcl commands.  The
       last  argument to Tcl_VarEval must be NULL to indicate the
       end of arguments.

       Tcl_EvalFile reads the file given by fileName  and  evalu-
       ates  its  contents  as a Tcl command by calling Tcl_Eval.
       It returns a standard Tcl result that reflects the  result
       of evaluating the file.  If the file couldn't be read then
       a Tcl error is returned to describe why the file  couldn't
       be read.

       Tcl_GlobalEval  is similar to Tcl_Eval except that it pro-
       cesses the command at global level.  This means  that  the
       variable  context for the command consists of global vari-
       ables 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 con-
       ditionals, loops, and procedures are implemented).   If  a
       code  other than TCL_OK is returned from a nested Tcl_Eval
       invocation, then the caller should normally return immedi-
       ately,  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_Eval  keeps  track of how many nested Tcl_Eval invoca-
       tions  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_Eval invocation for  interp,
       then  Tcl_Eval  converts  the return code to TCL_ERROR and
       sets interp->result to point to an error message  indicat-
       ing  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_Eval other then TCL_OK or TCL_ERROR.

KEYWORDS

       command, execute, file, global, interpreter, variable