NAME

       Tcl_EvalObjEx,   Tcl_EvalFile,   Tcl_EvalObjv,   Tcl_Eval,
       Tcl_EvalEx,       Tcl_GlobalEval,       Tcl_GlobalEvalObj,
       Tcl_VarEval, Tcl_VarEvalVA - execute Tcl scripts


SYNOPSIS

       #include <tcl.h>

       int                                                        |
       Tcl_EvalObjEx(interp, objPtr, flags)                       |

       int                                                        |
       Tcl_EvalFile(interp, fileName)                             |

       int                                                        |
       Tcl_EvalObjv(interp, objc, objv, flags)                    |

       int                                                        |
       Tcl_Eval(interp, script)                                   |

       int                                                        |
       Tcl_EvalEx(interp, script, numBytes, flags)                |

       int                                                        |
       Tcl_GlobalEval(interp, script)                             |

       int                                                        |
       Tcl_GlobalEvalObj(interp, objPtr, flags)                   |

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

       int                                                        |
       Tcl_VarEvalVA(interp, argList)                             |


ARGUMENTS |

       Tcl_Interp   *interp      (in)                                    ||
                                           Interpreter  in  which |
                                           to execute the script. |
                                           The      interpreter's |
                                           result  is modified to |
                                           hold  the  result   or |
                                           error message from the |
                                           script.                |

       Tcl_Obj      *objPtr      (in)                                    ||
                                           A  Tcl object contain­ |
                                           ing the script to exe­ |
                                           cute.                  |

       int          flags        (in)                                    ||
                                           ORed  combination   of |

                                           additional    options. |
                                           TCL_EVAL_GLOBAL    and |
                                           TCL_EVAL_DIRECT    are |
                                           currently supported.   |

       char         *fileName    (in)                                    ||
                                           Name of  a  file  con­ |
                                           taining  a Tcl script. |

       int          objc         (in)                                    ||
                                           The  number of objects |
                                           in the  array  pointed |
                                           to  by objPtr; this is |
                                           also  the  number   of |
                                           words  in the command. |

       Tcl_Obj      **objv       (in)                                    ||
                                           Points  to an array of |
                                           pointers  to  objects; |
                                           each  object holds the |
                                           value of a single word |
                                           in the command to exe­ |
                                           cute.                  |

       int          numBytes     (in)                                    ||
                                           The number of bytes in |
                                           script, not  including |
                                           any  null  terminating |
                                           character.    If   -1, |
                                           then all characters up |
                                           to the first null byte |
                                           are used.              |

       char         *script      (in)                                    ||
                                           Points to  first  byte |
                                           of  script  to execute |
                                           (NULL  terminated  and |
                                           UTF-8).   This  script |
                                           must  be  in  writable |
                                           memory: temporary mod­ |
                                           ifications are made to |
                                           it during parsing.     |

       char         *string      (in)                                    ||
                                           String forming part of |
                                           a Tcl script.          |

       va_list      argList      (in)                                    ||
                                           An argument list which |
                                           must  have  been  ini­ |
                                           tialised         using |
                                           TCL_VARARGS_START, and |
                                           cleared using  va_end. |



DESCRIPTION |

       The  procedures  described here are invoked to execute Tcl |
       scripts in various forms.  Tcl_EvalObjEx is the core  pro­ |
       cedure and is used by many of the others.  It executes the |
       commands in the script stored in objPtr  until  either  an |
       error occurs or the end of the script is reached.  If this |
       is the first time objPtr has been executed,  its  commands |
       are  compiled  into  bytecode  instructions which are then |
       executed.  The bytecodes are saved in objPtr so  that  the |
       compilation step can be skipped if the object is evaluated |
       again in the future.                                       |

       The return value from Tcl_EvalObjEx  (and  all  the  other |
       procedures  described  here) is a Tcl completion code with |
       one  of  the   values   TCL_OK,   TCL_ERROR,   TCL_RETURN, |
       TCL_BREAK,  or  TCL_CONTINUE.  In addition, a result value |
       or error message is left in interp's  result;  it  can  be |
       retrieved using Tcl_GetObjResult.                          |

       Tcl_EvalFile  reads  the file given by fileName and evalu­ |
       ates its contents as a Tcl script.  It  returns  the  same |
       information  as  Tcl_EvalObjEx.   If  the file couldn't be |
       read then a Tcl error is returned to describe why the file |
       couldn't be read.                                          |

       Tcl_EvalObjv  executes a single pre-parsed command instead |
       of a script.  The objc and objv arguments contain the val­ |
       ues  of  the  words  for the Tcl command, one word in each |
       object in objv.  Tcl_EvalObjv evaluates  the  command  and |
       returns a completion code and result just like Tcl_EvalOb­ |
       jEx.                                                       |

       Tcl_Eval is  similar  to  Tcl_EvalObjEx  except  that  the |
       script  to  be executed is supplied as a string instead of |
       an object and no compilation occurs.  The string should be |
       a  proper UTF-8 string as converted by Tcl_ExternalToUtfD­ |
       String or Tcl_ExternalToUtf when it is known  to  possibly |
       contain upper ascii characters who's possible combinations |
       might be a UTF-8 special code.  The string is  parsed  and |
       executed  directly (using Tcl_EvalObjv) instead of compil­ |
       ing it and executing the bytecodes.  In  situations  where |
       it  is known that the script will never be executed again, |
       Tcl_Eval  may  be  faster  than  Tcl_EvalObjEx.   Tcl_Eval |
       returns a completion code and result just like Tcl_EvalOb­ |
       jEx.   Note:  for  backward  compatibility  with  versions |
       before  Tcl  8.0,  Tcl_Eval  copies  the  object result in |
       interp to interp->result (use is deprecated) where it  can |
       be accessed directly.  This makes Tcl_Eval somewhat slower |
       than Tcl_EvalEx, which doesn't do the copy.                |

       Tcl_EvalEx is an extended version of Tcl_Eval  that  takes |

       ciency reason given above, Tcl_EvalEx  is  generally  pre­ |
       ferred over Tcl_Eval.                                      |

       Tcl_GlobalEval  and Tcl_GlobalEvalObj are older procedures |
       that are now deprecated.  They are similar  to  Tcl_EvalEx |
       and  Tcl_EvalObjEx  except that the script is evaluated in |
       the global namespace and its variable context consists  of |
       global  variables only (it ignores any Tcl procedures that |
       are active).  These functions are equivalent to using  the |
       TCL_EVAL_GLOBAL flag (see below).                          |

       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  same  way  as Tcl_Eval.  The last |
       argument to Tcl_VarEval must be NULL to indicate  the  end |
       of arguments.  Tcl_VarEval is now deprecated.              |

       Tcl_VarEvalVA  is  the  same  as  Tcl_VarEval  except that |
       instead of taking a variable number of arguments it  takes |
       an  argument list. Like Tcl_VarEval, Tcl_VarEvalVA is dep­ |
       recated.                                                   |


FLAG BITS |

       Any ORed combination of the following values may  be  used |
       for  the  flags argument to procedures such as Tcl_EvalOb­ |
       jEx:                                                       |

       TCL_EVAL_DIRECT                                                   ||
                              This flag is only used by Tcl_Eval­ |
                              ObjEx; it is ignored by other  pro­ |
                              cedures.   If this flag bit is set, |
                              the script is not compiled to byte­ |
                              codes;   instead   it  is  executed |
                              directly as is done by  Tcl_EvalEx. |
                              The  TCL_EVAL_DIRECT flag is useful |
                              in situations where the contents of |
                              an object are going to change imme­ |
                              diately, so the bytecodes won't  be |
                              reused  in  a future execution.  In |
                              this case, it's faster  to  execute |
                              the script directly.                |

       TCL_EVAL_GLOBAL                                                   ||
                              If this flag is set, the script  is |
                              processed  at  global  level.  This |
                              means that it is evaluated  in  the |
                              global  namespace  and its variable |
                              context consists  of  global  vari­ |
                              ables only (it ignores any Tcl pro­ |
                              cedures at are active).             |

       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_EvalObjEx 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_EvalObjEx keeps track of how many nested Tcl_EvalObjEx |
       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_EvalObjEx  invocation  for |
       interp,  it converts the return code to TCL_ERROR and sets |
       interp's result to an error message  indicating  that  the |
       return, break, or continue command was invoked in an inap­ |
       propriate place.  This means that  top-level  applications |
       should  never  see  a return code from Tcl_EvalObjEx other |
       then TCL_OK or TCL_ERROR.


KEYWORDS

       execute, file, global, object, result, script


Man(1) output converted with man2html