Tcl_ObjSetVar2(3) Tcl (8.0) Tcl_ObjSetVar2(3)
_________________________________________________________________
NAME
Tcl_ObjSetVar2, Tcl_ObjGetVar2 - manipulate Tcl variables
SYNOPSIS
#include <tcl.h>
Tcl_Obj *
Tcl_ObjSetVar2(interp, part1Ptr, part2Ptr, newValuePtr, flags)
Tcl_Obj *
Tcl_ObjGetVar2(interp, part1Ptr, part2Ptr, flags)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter containing
variable.
Tcl_Obj *part1Ptr (in) Points to a Tcl object
containing the
variable's name. The
name may include a
series of :: namespace
qualifiers to specify
a variable in a
particular namespace.
May refer to a scalar
variable or an element
of an array variable.
Tcl_Obj *part2Ptr (in) If non-NULL, points to
an object containing
the name of an element
within an array and
part1Ptr must refer to
an array variable.
Tcl_Obj *newValuePtr (in) Points to a Tcl object
containing the new
value for the
variable.
int flags (in) OR-ed combination of
bits providing
additional information
for operation. See
below for valid
values.
_________________________________________________________________
DESCRIPTION
Page 1 (printed 2/19/99)
Tcl_ObjSetVar2(3) Tcl (8.0) Tcl_ObjSetVar2(3)
These two procedures may be used to read and modify Tcl
variables from C code. Tcl_ObjSetVar2 will create a new
variable or modify an existing one. It sets the specified
variable to the object referenced by newValuePtr and returns
a pointer to the object which is the variable's new value.
The returned object may not be the same one referenced by
newValuePtr; this might happen because variable traces may
modify the variable's value. The reference count for the
variable's old value is decremented and the reference count
for its new value is incremented. If the new value for the
variable is not the same one referenced by newValuePtr
(perhaps as a result of a variable trace), then
newValuePtr's reference count is left unchanged. The
reference count for the returned object is not incremented
to reflect the returned reference. If the caller needs to
keep a reference to the object, say in a data structure, it
must increment its reference count using Tcl_IncrRefCount.
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 variable name specified to Tcl_ObjSetVar2 consists of
two parts. part1Ptr contains the name of a scalar or array
variable. If part2Ptr is NULL, the variable must be a
scalar. If part2Ptr is not NULL, it contains the name of an
element in the array named by part2Ptr. As a special case,
if the flag TCL_PARSE_PART1 is specified, part1Ptr may
contain both an array and an element name: if the name
contains an open parenthesis and ends with a close
parenthesis, then the value between the parentheses is
treated as an element name (which can have any string value)
and the characters before the first open parenthesis are
treated as the name of an array variable. If the flag
TCL_PARSE_PART1 is given, part2Ptr should be NULL since the
array and element names are taken from part2Ptr.
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 as follows: If a procedure call is active in
interp, a variable is looked up at the current level of
procedure call. Otherwise, a variable is looked up
first in the current namespace, then in the global
namespace. However, if this bit is set in flags then
the variable is looked up only in the global namespace
even if there is a procedure call active. If both
TCL_GLOBAL_ONLY and TCL_NAMESPACE_ONLY are given,
TCL_GLOBAL_ONLY is ignored.
Page 2 (printed 2/19/99)
Tcl_ObjSetVar2(3) Tcl (8.0) Tcl_ObjSetVar2(3)
TCL_NAMESPACE_ONLY
Under normal circumstances the procedures look up
variables as follows: If a procedure call is active in
interp, a variable is looked up at the current level of
procedure call. Otherwise, a variable is looked up
first in the current namespace, then in the global
namespace. However, if this bit is set in flags then
the variable is looked up only in the current namespace
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 the interpreter's
result, where it can be retrieved with Tcl_GetObjResult
or Tcl_GetStringResult. If this flag bit isn't set
then no error message is left and the interpreter's
result will not be modified.
TCL_APPEND_VALUE
If this bit is set then newValuePtr 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 newValuePtr 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 `` }'').
TCL_PARSE_PART1
If this bit is set, then Tcl_ObjGetVar2 and
Tcl_ObjSetVar2 will parse part1Ptr to obtain both an
array name and an element name. If the name in
part1Ptr contains an open parenthesis and ends with a
close parenthesis, the name is treated as the name of
an element of an array; otherwise, the name in part1Ptr
is interpreted as the name of a scalar variable. When
this bit is set, part2Ptr is ignored.
Tcl_ObjGetVar2 returns the value of the specified variable.
Its arguments are treated the same way as those for
Tcl_ObjSetVar2. It returns a pointer to the object which is
the variable's value. The reference count for the returned
object is not incremented. If the caller needs to keep a
reference to the object, say in a data structure, it must
increment the reference count using Tcl_IncrRefCount. If an
error occurs in setting the variable (e.g. an array variable
is referenced without giving an index into the array), then
Page 3 (printed 2/19/99)
Tcl_ObjSetVar2(3) Tcl (8.0) Tcl_ObjSetVar2(3)
NULL is returned.
SEE ALSO
Tcl_GetObjResult, Tcl_GetStringResult, Tcl_GetVar,
Tcl_GetVar2, Tcl_SetVar, Tcl_SetVar2, Tcl_TraceVar,
Tcl_UnsetVar, Tcl_UnsetVar2
KEYWORDS
array, interpreter, object, scalar, set, unset, variable
Page 4 (printed 2/19/99)
