tcl7.6 C API - SetVar






NAME

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


SYNOPSIS

     #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

     Tcl_Interp   *interp     (in)      Interpreter    containing
                                        variable.

     char         *varName    (in)      Name  of  variable.   May
                                        refer  to  a scalar vari-
                                        able or an element of  an
                                        array  variable.   If the
                                        name references  an  ele-
                                        ment 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   opera-
                                        tion. 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.





DESCRIPTION

     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 vari-
     able structure.  Tcl keeps a private copy of the  variable's
     value,  so  the  caller may change newValue after these pro-
     cedures 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 combina-
     tion of any of the following bits:

     TCL_GLOBAL_ONLY
          Under normal circumstances the procedures look up vari-
          ables  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  pro-
          cedure 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 vari-
          able 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 sin-
          gle character ``{'', or ends in `` }'').

     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  vari-
     able), then NULL is returned.

     Tcl_UnsetVar and Tcl_UnsetVar2 may be used to remove a vari-
     able,  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  speci-
     fied without an index, then the entire array is removed.



SEE ALSO

     Tcl_TraceVar



KEYWORDS

     array, interpreter, scalar, set, unset, variable