Tcl_SetVar(3Tcl)					      Tcl_SetVar(3Tcl)

NAME    [Toc]    [Back]

     Tcl_SetVar, Tcl_SetVar2, Tcl_GetVar, Tcl_GetVar2, Tcl_UnsetVar,
     Tcl_UnsetVar2 - manipulate	Tcl variables

SYNOPSIS    [Toc]    [Back]

     #include <tcl.h>

     char *
     Tcl_SetVar(interp,	varName, newValue, flags)

     char *
     Tcl_SetVar2(interp, name1,	name2, newValue, flags)

     char *
     Tcl_GetVar(interp,	varName, flags)

     char *
     Tcl_GetVar2(interp, name1,	name2, flags)

     int
     Tcl_UnsetVar(interp, varName, flags)

     int
     Tcl_UnsetVar2(interp, name1, name2, flags)

ARGUMENTS    [Toc]    [Back]

     Tcl_Interp	  *interp     (in)	Interpreter containing variable.

     char	  *varName    (in)	Name of	variable.  May refer to	a
					scalar variable	or an element of an
					array variable.	 If the	name	      |
					references an element of an array,    |
					then it	must be	in writable memory:   |
					Tcl will make temporary	modifications |
					to it while looking up the name.

     char	  *newValue   (in)	New value for variable.

     int	  flags	      (in)	OR-ed combination of bits providing
					additional information for operation.
					See below for valid values.

     char	  *name1      (in)	Name of	scalar variable, or name of
					array variable if name2	is non-NULL.

     char	  *name2      (in)	If non-NULL, gives name	of element
					within array and name1 must refer to
					an array variable.







									Page 1






Tcl_SetVar(3Tcl)					      Tcl_SetVar(3Tcl)

DESCRIPTION    [Toc]    [Back]

     These procedures may be used to create, modify, read, and delete Tcl
     variables from C code.  Tcl_SetVar	and Tcl_SetVar2	will create a new
     variable or modify	an existing one.  Both of these	procedures set the
     given variable to the value given by newValue, and	they return a pointer
     to	a copy of the variable's new value, which is stored in Tcl's variable
     structure.	 Tcl keeps a private copy of the variable's value, so the
     caller may	change newValue	after these procedures return without
     affecting the value of the	variable.  If an error occurs in setting the
     variable (e.g. an array variable is referenced without giving an index
     into the array), then NULL	is returned.

     The name of the variable may be specified in either of two	ways.  If
     Tcl_SetVar	is called, the variable	name is	given as a single string,
     varName.  If varName contains an open parenthesis and ends	with a close
     parenthesis, then the value between the parentheses is treated as an
     index (which can have any string value) and the characters	before the
     first open	parenthesis are	treated	as the name of an array	variable.  If
     varName doesn't have parentheses as described above, then the entire
     string is treated as the name of a	scalar variable.  If Tcl_SetVar2 is
     called, then the array name and index have	been separated by the caller
     into two separate strings,	name1 and name2	respectively;  if name2	is
     zero it means that	a scalar variable is being referenced.

     The flags argument	may be used to specify any of several options to the
     procedures.  It consists of an OR-ed combination of any of	the following
     bits:

     TCL_GLOBAL_ONLY
	  Under	normal circumstances the procedures look up variables at the
	  current level	of procedure call for interp, or at global level if
	  there	is no call active.  However, if	this bit is set	in flags then
	  the variable is looked up at global level even if there is a
	  procedure call active.

     TCL_LEAVE_ERR_MSG
	  If an	error is returned and this bit is set in flags,	then an	error
	  message will be left in interp->result.  If this flag	bit isn't set
	  then no error	message	is left	(interp->result	will not be modified).

     TCL_APPEND_VALUE
	  If this bit is set then newValue is appended to the current value,
	  instead of replacing it.  If the variable is currently undefined,
	  then this bit	is ignored.

     TCL_LIST_ELEMENT
	  If this bit is set, then newValue is converted to a valid Tcl	list
	  element before setting (or appending to) the variable.  A separator
	  space	is appended before the new list	element	unless the list	      |
	  element is going to be the first element in a	list or	sublist	(i.e. |
	  the variable's current value is empty, or contains the single	      |
	  character ``{'', or ends in `` }'').



									Page 2






Tcl_SetVar(3Tcl)					      Tcl_SetVar(3Tcl)



     Tcl_GetVar	and Tcl_GetVar2	return the current value of a variable.	 The
     arguments to these	procedures are treated in the same way as the
     arguments to Tcl_SetVar and Tcl_SetVar2.  Under normal circumstances, the
     return value is a pointer to the variable's value (which is stored	in
     Tcl's variable structure and will not change before the next call to
     Tcl_SetVar	or Tcl_SetVar2).  The only bits	of flags that are used are
     TCL_GLOBAL_ONLY and TCL_LEAVE_ERR_MSG, both of which have the same
     meaning as	for Tcl_SetVar.	 If an error occurs in reading the variable
     (e.g. the variable	doesn't	exist or an array element is specified for a
     scalar variable), then NULL is returned.

     Tcl_UnsetVar and Tcl_UnsetVar2 may	be used	to remove a variable, so that
     future calls to Tcl_GetVar	or Tcl_GetVar2 for the variable	will return an
     error.  The arguments to these procedures are treated in the same way as
     the arguments to Tcl_GetVar and Tcl_GetVar2.  If the variable is	      |
     successfully removed then TCL_OK is returned.  If the variable cannot be |
     removed because it	doesn't	exist then TCL_ERROR is	returned.  If an array
     element is	specified, the given element is	removed	but the	array remains.
     If	an array name is specified without an index, then the entire array is
     removed.

SEE ALSO    [Toc]    [Back]

     Tcl_TraceVar

KEYWORDS    [Toc]    [Back]

     array, interpreter, scalar, set, unset, variable


									PPPPaaaaggggeeee 3333