通讯编程

开发平台：
Visual C++

Eval.3：源码内容
							'"
'" Copyright (c) 1989-1993 The Regents of the University of California.
'" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'" Copyright (c) 2000 Scriptics Corporation.
'"
'" See the file "license.terms" for information on usage and redistribution
'" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'" 
'" RCS: @(#) $Id: Eval.3,v 1.12.2.3 2003/07/18 16:56:24 dgp Exp $
'" 
.so man.macros
.TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA - execute Tcl scripts
.SH SYNOPSIS
.nf
fB#include <tcl.h>fR
.sp
.VS
int
fBTcl_EvalObjExfR(fIinterp, objPtr, flagsfR)
.sp
int
fBTcl_EvalFilefR(fIinterp, fileNamefR)
.sp
int
fBTcl_EvalObjvfR(fIinterp, objc, objv, flagsfR)
.sp
int
fBTcl_EvalfR(fIinterp, scriptfR)
.sp
int
fBTcl_EvalExfR(fIinterp, script, numBytes, flagsfR)
.sp
int
fBTcl_GlobalEvalfR(fIinterp, scriptfR)
.sp
int
fBTcl_GlobalEvalObjfR(fIinterp, objPtrfR)
.sp
int
fBTcl_VarEvalfR(fIinterp, string, string, ... fB(char *) NULLfR)
.sp
int
fBTcl_VarEvalVAfR(fIinterp, argListfR)
.SH ARGUMENTS
.AS Tcl_Interp **termPtr;
.AP 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.
.AP Tcl_Obj *objPtr in
A Tcl object containing the script to execute.
.AP int flags in
ORed combination of flag bits that specify additional options.
fBTCL_EVAL_GLOBALfR and fBTCL_EVAL_DIRECTfR are currently supported.
.AP "CONST char" *fileName in
Name of a file containing a Tcl script.
.AP int objc in
The number of objects in the array pointed to by fIobjPtrfR;
this is also the number of words in the command.
.AP 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 execute.
.AP int numBytes in
The number of bytes in fIscriptfR, not including any
null terminating character.  If -1, then all characters up to the
first null byte are used.
.AP "CONST char" *script in
Points to first byte of script to execute (null-terminated and UTF-8).
.AP char *string in
String forming part of a Tcl script.
.AP va_list argList in
An argument list which must have been initialised using
fBTCL_VARARGS_STARTfR, and cleared using fBva_endfR.
.BE
.SH DESCRIPTION
.PP
The procedures described here are invoked to execute Tcl scripts in
various forms.
fBTcl_EvalObjExfR is the core procedure and is used by many of the others.
It executes the commands in the script stored in fIobjPtrfR
until either an error occurs or the end of the script is reached.
If this is the first time fIobjPtrfR has been executed,
its commands are compiled into bytecode instructions
which are then executed.  The
bytecodes are saved in fIobjPtrfR so that the compilation step
can be skipped if the object is evaluated again in the future.
.PP
The return value from fBTcl_EvalObjExfR (and all the other procedures
described here) is a Tcl completion code with
one of the values fBTCL_OKfR, fBTCL_ERRORfR, fBTCL_RETURNfR,
fBTCL_BREAKfR, or fBTCL_CONTINUEfR, or possibly some other
integer value originating in an extension.
In addition, a result value or error message is left in fIinterpfR's
result; it can be retrieved using fBTcl_GetObjResultfR.
.PP
fBTcl_EvalFilefR reads the file given by fIfileNamefR and evaluates
its contents as a Tcl script.  It returns the same information as
fBTcl_EvalObjExfR.
If the file couldn't be read then a Tcl error is returned to describe
why the file couldn't be read.
.VS 8.4
The eofchar for files is '\32' (^Z) for all platforms.
If you require a ``^Z'' in code for string comparison, you can use
``\032'' or ``\u001a'', which will be safely substituted by the Tcl
interpreter into ``^Z''.
.VE 8.4
.PP
fBTcl_EvalObjvfR executes a single pre-parsed command instead of a
script.  The fIobjcfR and fIobjvfR arguments contain the values
of the words for the Tcl command, one word in each object in
fIobjvfR.  fBTcl_EvalObjvfR evaluates the command and returns
a completion code and result just like fBTcl_EvalObjExfR.
.PP
fBTcl_EvalfR is similar to fBTcl_EvalObjExfR 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
fBTcl_ExternalToUtfDStringfR or fBTcl_ExternalToUtffR 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 fBTcl_EvalObjvfR) instead of compiling it and executing the
bytecodes.  In situations where it is known that the script will never be
executed again, fBTcl_EvalfR may be faster than fBTcl_EvalObjExfR.
 fBTcl_EvalfR returns a completion code and result just like 
fBTcl_EvalObjExfR.  Note: for backward compatibility with versions before
Tcl 8.0, fBTcl_EvalfR copies the object result in fIinterpfR to
fIinterp->resultfR (use is deprecated) where it can be accessed directly.
 This makes fBTcl_EvalfR somewhat slower than fBTcl_EvalExfR, which
doesn't do the copy.
.PP
fBTcl_EvalExfR is an extended version of fBTcl_EvalfR that takes
additional arguments fInumBytesfR and fIflagsfR.  For the
efficiency reason given above, fBTcl_EvalExfR is generally preferred
over fBTcl_EvalfR.
.PP
fBTcl_GlobalEvalfR and fBTcl_GlobalEvalObjfR are older procedures
that are now deprecated.  They are similar to fBTcl_EvalExfR and
fBTcl_EvalObjExfR 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 fBTCL_EVAL_GLOBALfR flag (see below).
.PP
fBTcl_VarEvalfR takes any number of string arguments
of any length, concatenates them into a single string,
then calls fBTcl_EvalfR to execute that string as a Tcl command.
It returns the result of the command and also modifies
fIinterp->resultfR in the same way as fBTcl_EvalfR.
The last argument to fBTcl_VarEvalfR must be NULL to indicate the end
of arguments.  fBTcl_VarEvalfR is now deprecated.
.PP
fBTcl_VarEvalVAfR is the same as fBTcl_VarEvalfR except that
instead of taking a variable number of arguments it takes an argument
list. Like fBTcl_VarEvalfR, fBTcl_VarEvalVAfR is deprecated.
.SH "FLAG BITS"
Any ORed combination of the following values may be used for the
fIflagsfR argument to procedures such as fBTcl_EvalObjExfR:
.TP 23
fBTCL_EVAL_DIRECTfR
This flag is only used by fBTcl_EvalObjExfR; it is ignored by
other procedures.  If this flag bit is set, the script is not
compiled to bytecodes; instead it is executed directly
as is done by fBTcl_EvalExfR.  The
fBTCL_EVAL_DIRECTfR flag is useful in situations where the
contents of an object are going to change immediately, so the
bytecodes won't be reused in a future execution.  In this case,
it's faster to execute the script directly.
.TP 23
fBTCL_EVAL_GLOBALfR
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 variables only (it ignores any Tcl
procedures at are active).
.SH "MISCELLANEOUS DETAILS"
.PP
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 fBTCL_OKfR is returned
from a nested fBTcl_EvalObjExfR 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 fBforfR, will check for certain
return codes, like fBTCL_BREAKfR and fBTCL_CONTINUEfR, and process them
specially without returning.
.PP
fBTcl_EvalObjExfR keeps track of how many nested fBTcl_EvalObjExfR
invocations are in progress for fIinterpfR.
If a code of fBTCL_RETURNfR, fBTCL_BREAKfR, or fBTCL_CONTINUEfR is
about to be returned from the topmost fBTcl_EvalObjExfR
invocation for fIinterpfR,
it converts the return code to fBTCL_ERRORfR
and sets fIinterpfR's result to an error message indicating that
the fBreturnfR, fBbreakfR, or fBcontinuefR command was
invoked in an inappropriate place.
This means that top-level applications should never see a return code
from fBTcl_EvalObjExfR other then fBTCL_OKfR or fBTCL_ERRORfR.
.VE
.SH KEYWORDS
execute, file, global, object, result, script

						