ObjSetVar man page on DigitalUNIX

Printed from http://www.polarhome.com/service/man/?qf=ObjSetVar&af=0&tf=2&of=DigitalUNIX

Tcl_ObjSetVar2(3)	    Tcl Library Procedures	     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 :: names‐
					     pace  qualifiers  to  specify   a
					     variable  in  a particular names‐
					     pace.   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 provid‐
					     ing  additional  information  for
					     operation. See  below  for	 valid
					     values.
_________________________________________________________________

DESCRIPTION
       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	exist‐
       ing  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  newVal‐
       uePtr'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_IncrRef‐
       Count.  If an error occurs in setting the variable (e.g. an array vari‐
       able 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 follow‐
       ing 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.

       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	inter‐
	      preted  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	 argu‐
       ments 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 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

Tcl				      8.0		     Tcl_ObjSetVar2(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net