1Tcl_SetVar(3)               Tcl Library Procedures               Tcl_SetVar(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_SetVar2Ex,  Tcl_SetVar, Tcl_SetVar2, Tcl_ObjSetVar2, Tcl_GetVar2Ex,
9       Tcl_GetVar, Tcl_GetVar2, Tcl_ObjGetVar2, Tcl_UnsetVar, Tcl_UnsetVar2  -
10       manipulate Tcl variables
11

SYNOPSIS

13       #include <tcl.h>
14
15       Tcl_Obj *
16       Tcl_SetVar2Ex(interp, name1, name2, newValuePtr, flags)
17
18       const char *
19       Tcl_SetVar(interp, varName, newValue, flags)
20
21       const char *
22       Tcl_SetVar2(interp, name1, name2, newValue, flags)
23
24       Tcl_Obj *
25       Tcl_ObjSetVar2(interp, part1Ptr, part2Ptr, newValuePtr, flags)
26
27       Tcl_Obj *
28       Tcl_GetVar2Ex(interp, name1, name2, flags)
29
30       const char *
31       Tcl_GetVar(interp, varName, flags)
32
33       const char *
34       Tcl_GetVar2(interp, name1, name2, flags)
35
36       Tcl_Obj *
37       Tcl_ObjGetVar2(interp, part1Ptr, part2Ptr, flags)
38
39       int
40       Tcl_UnsetVar(interp, varName, flags)
41
42       int
43       Tcl_UnsetVar2(interp, name1, name2, flags)
44

ARGUMENTS

46       Tcl_Interp *interp (in)               Interpreter containing variable.
47
48       const char *name1 (in)                Contains  the  name  of  an array
49                                             variable (if name2  is  non-NULL)
50                                             or  (if name2 is NULL) either the
51                                             name of a scalar  variable  or  a
52                                             complete   name   including  both
53                                             variable  name  and  index.   May
54                                             include  ::  namespace qualifiers
55                                             to specify a variable in  a  par‐
56                                             ticular namespace.
57
58       const char *name2 (in)                If  non-NULL,  gives name of ele‐
59                                             ment within array; in  this  case
60                                             name1  must  refer  to  an  array
61                                             variable.
62
63       Tcl_Obj *newValuePtr (in)             Points to a Tcl object containing
64                                             the new value for the variable.
65
66       int flags (in)                        OR-ed combination of bits provid‐
67                                             ing additional  information.  See
68                                             below for valid values.
69
70       const char *varName (in)              Name of variable.  May include ::
71                                             namespace qualifiers to specify a
72                                             variable  in  a particular names‐
73                                             pace.   May  refer  to  a  scalar
74                                             variable  or  an  element  of  an
75                                             array.
76
77       const char *newValue (in)             New value for variable, specified
78                                             as  a  null-terminated string.  A
79                                             copy of this value is  stored  in
80                                             the variable.
81
82       Tcl_Obj *part1Ptr (in)                Points to a Tcl object containing
83                                             the variable's  name.   The  name
84                                             may include a series of :: names‐
85                                             pace  qualifiers  to  specify   a
86                                             variable  in  a particular names‐
87                                             pace.   May  refer  to  a  scalar
88                                             variable  or  an  element  of  an
89                                             array variable.
90
91       Tcl_Obj *part2Ptr (in)                If non-NULL, points to an  object
92                                             containing the name of an element
93                                             within an array and part1Ptr must
94                                             refer to an array variable.
95_________________________________________________________________
96
97

DESCRIPTION

99       These procedures are used to create, modify, read, and delete Tcl vari‐
100       ables from C code.
101
102       Tcl_SetVar2Ex, Tcl_SetVar, Tcl_SetVar2, and Tcl_ObjSetVar2 will  create
103       a  new  variable  or  modify an existing one.  These procedures set the
104       given variable to the value given by newValuePtr or newValue and return
105       a  pointer  to the variable's new value, which is stored in Tcl's vari‐
106       able structure.  Tcl_SetVar2Ex and Tcl_ObjSetVar2 take the new value as
107       a  Tcl_Obj  and return a pointer to a Tcl_Obj.  Tcl_SetVar and Tcl_Set‐
108       Var2 take the new value as a string and return a string; they are  usu‐
109       ally  less  efficient  than Tcl_ObjSetVar2.  Note that the return value
110       may be different than the newValuePtr or newValue argument, due to mod‐
111       ifications  made  by  write  traces.  If an error occurs in setting the
112       variable (e.g. an array variable is referenced without giving an  index
113       into  the  array)  NULL  is  returned  and  an error message is left in
114       interp's result if the TCL_LEAVE_ERR_MSG flag bit is set.
115
116       Tcl_GetVar2Ex, Tcl_GetVar, Tcl_GetVar2, and Tcl_ObjGetVar2  return  the
117       current  value  of  a  variable.  The arguments to these procedures are
118       treated in the same way as the arguments to  the  procedures  described
119       above.   Under  normal  circumstances, the return value is a pointer to
120       the variable's value.  For Tcl_GetVar2Ex and Tcl_ObjGetVar2  the  value
121       is  returned as a pointer to a Tcl_Obj.  For Tcl_GetVar and Tcl_GetVar2
122       the value is returned as a string; this is usually less  efficient,  so
123       Tcl_GetVar2Ex  or  Tcl_ObjGetVar2  are  preferred.   If an error occurs
124       while reading the variable (e.g. the variable  does  not  exist  or  an
125       array  element  is  specified  for  a  scalar  variable),  then NULL is
126       returned and an error  message  is  left  in  interp's  result  if  the
127       TCL_LEAVE_ERR_MSG flag bit is set.
128
129       Tcl_UnsetVar  and  Tcl_UnsetVar2  may  be used to remove a variable, so
130       that future attempts to read the variable will return  an  error.   The
131       arguments  to these procedures are treated in the same way as the argu‐
132       ments to the procedures above.  If the variable is successfully removed
133       then  TCL_OK is returned.  If the variable cannot be removed because it
134       does not exist then TCL_ERROR is returned and an error message is  left
135       in  interp's  result  if  the TCL_LEAVE_ERR_MSG flag bit is set.  If an
136       array element is specified, the given element is removed but the  array
137       remains.   If  an  array  name  is specified without an index, then the
138       entire array is removed.
139
140       The name of a variable may be specified to  these  procedures  in  four
141       ways:
142
143       [1]    If Tcl_SetVar, Tcl_GetVar, or Tcl_UnsetVar is invoked, the vari‐
144              able name is given as a single string, varName.  If varName con‐
145              tains  an  open  parenthesis  and ends with a close parenthesis,
146              then the value between the parentheses is treated  as  an  index
147              (which  can have any string value) and the characters before the
148              first open parenthesis are treated as the name of an array vari‐
149              able.   If varName does not have parentheses as described above,
150              then the entire string is treated as the name of a scalar  vari‐
151              able.
152
153       [2]    If  the name1 and name2 arguments are provided and name2 is non-
154              NULL, then an array element is specified and the array name  and
155              index  have already been separated by the caller: name1 contains
156              the name and name2 contains the index.  An error is generated if
157              name1  contains an open parenthesis and ends with a close paren‐
158              thesis (array element) and name2 is non-NULL.
159
160       [3]    If name2 is NULL, name1 is treated just like varName in case [1]
161              above  (it  can  be either a scalar or an array element variable
162              name).
163
164       The flags argument may be used to specify any of several options to the
165       procedures.  It consists of an OR-ed combination of the following bits.
166
167       TCL_GLOBAL_ONLY
168              Under  normal  circumstances the procedures look up variables as
169              follows.  If a procedure call is active in interp, the  variable
170              is looked up at the current level of procedure call.  Otherwise,
171              the variable is looked up first in the current  namespace,  then
172              in  the  global namespace.  However, if this bit is set in flags
173              then the variable is looked up only in the global namespace even
174              if  there  is  a procedure call active.  If both TCL_GLOBAL_ONLY
175              and TCL_NAMESPACE_ONLY are given, TCL_GLOBAL_ONLY is ignored.
176
177       TCL_NAMESPACE_ONLY
178              If this bit is set in flags then the variable is looked up  only
179              in the current namespace; if a procedure is active its variables
180              are ignored, and the global namespace is also ignored unless  it
181              is the current namespace.
182
183       TCL_LEAVE_ERR_MSG
184              If  an  error  is returned and this bit is set in flags, then an
185              error message will be left in the interpreter's result, where it
186              can  be  retrieved with Tcl_GetObjResult or Tcl_GetStringResult.
187              If this flag bit is not set then no error message  is  left  and
188              the interpreter's result will not be modified.
189
190       TCL_APPEND_VALUE
191              If  this  bit is set then newValuePtr or newValue is appended to
192              the current value instead of replacing it.  If the  variable  is
193              currently  undefined, then the bit is ignored.  This bit is only
194              used by the Tcl_Set* procedures.
195
196       TCL_LIST_ELEMENT
197              If this bit is set, then newValue is converted to  a  valid  Tcl
198              list  element  before setting (or appending to) the variable.  A
199              separator space is appended before the new list  element  unless
200              the  list  element is going to be the first element in a list or
201              sublist (i.e. the variable's current value is empty, or contains
202              the single character “{”, or ends in “ }”).  When appending, the
203              original value of the variable must also be  a  valid  list,  so
204              that the operation is the appending of a new list element onto a
205              list.
206
207       Tcl_GetVar and Tcl_GetVar2 return the current value of a variable.  The
208       arguments  to these procedures are treated in the same way as the argu‐
209       ments to Tcl_SetVar and Tcl_SetVar2.  Under normal  circumstances,  the
210       return  value  is a pointer to the variable's value (which is stored in
211       Tcl's variable structure and will not change before the  next  call  to
212       Tcl_SetVar  or  Tcl_SetVar2).   Tcl_GetVar and Tcl_GetVar2 use the flag
213       bits TCL_GLOBAL_ONLY and TCL_LEAVE_ERR_MSG, both of which have the same
214       meaning  as for Tcl_SetVar.  If an error occurs in reading the variable
215       (e.g. the variable does not exist or an array element is specified  for
216       a scalar variable), then NULL is returned.
217
218       Tcl_UnsetVar  and  Tcl_UnsetVar2  may  be used to remove a variable, so
219       that future calls to Tcl_GetVar or Tcl_GetVar2 for  the  variable  will
220       return  an error.  The arguments to these procedures are treated in the
221       same way as the arguments to Tcl_GetVar and Tcl_GetVar2.  If the  vari‐
222       able  is successfully removed then TCL_OK is returned.  If the variable
223       cannot be removed because it does not exist then TCL_ERROR is returned.
224       If  an array element is specified, the given element is removed but the
225       array remains.  If an array name is specified without  an  index,  then
226       the entire array is removed.
227
228

SEE ALSO

230       Tcl_GetObjResult, Tcl_GetStringResult, Tcl_TraceVar
231
232

KEYWORDS

234       array, get variable, interpreter, object, scalar, set, unset, variable
235
236
237
238Tcl                                   8.1                        Tcl_SetVar(3)
Impressum