tcl7.6 C API - UpVar






NAME

     Tcl_UpVar, Tcl_UpVar2 - link one variable to another


SYNOPSIS

     #include <tcl.h>

     int
     Tcl_UpVar(interp, frameName, sourceName, destName, flags)

     int
     Tcl_UpVar2(interp, frameName, name1, name2, destName, flags)


ARGUMENTS

     Tcl_Interp         *interp          (in)      Interpreter
                                                   containing
                                                   variables;
                                                   also  used for
                                                   error  report-
                                                   ing.

     char               *frameName       (in)      Identifies the
                                                   stack    frame
                                                   containing
                                                   source   vari-
                                                   able.      May
                                                   have   any  of
                                                   the      forms
                                                   accepted    by
                                                   the upvar com-
                                                   mand,  such as
                                                   #0 or 1.

     char               *sourceName      (in)      Name of source
                                                   variable,   in
                                                   the      frame
                                                   given       by
                                                   frameName.
                                                   May refer to a
                                                   scalar   vari-
                                                   able  or to an
                                                   array variable
                                                   with         a
                                                   parenthesized
                                                   index.

     char               *destName        (in)      Name of desti-
                                                   nation   vari-
                                                   able, which is
                                                   to  be  linked
                                                   to      source
                                                   variable    so
                                                   that    refer-
                                                   ences to dest-
                                                   Name refer  to
                                                   the      other
                                                   variable.
                                                   Must       not
                                                   currently
                                                   exist   except
                                                   as an upvar-ed
                                                   variable.

     int                flags            (in)      Either
                                                   TCL_GLOBAL_ONLY
                                                   or   0;     if
                                                   non-zero, then
                                                   destName is  a
                                                   global   vari-
                                                   able;   other-
                                                   wise  it  is a
                                                   local  to  the
                                                   current   pro-
                                                   cedure     (or
                                                   global  if  no
                                                   procedure   is
                                                   active).

     char               *name1           (in)      First part  of
                                                   source
                                                   variable's
                                                   name   (scalar
                                                   name, or  name
                                                   of       array
                                                   without  array
                                                   index).

     char               *name2           (in)      If      source
                                                   variable is an
                                                   element of  an
                                                   array,   gives
                                                   the  index  of
                                                   the   element.
                                                   For     scalar
                                                   source   vari-
                                                   ables,      is
                                                   NULL.





DESCRIPTION

     Tcl_UpVar and Tcl_UpVar2 provide the same  functionality  as
     the  upvar command:  they make a link from a source variable
     to a destination variable, so that references to the  desti-
     nation  are passed transparently through to the source.  The
     name of the source variable may be  specified  either  as  a
     single string such as xyx or a(24) (by calling Tcl_UpVar) or
     in two parts where the array name has  been  separated  from
     the  element  name (by calling Tcl_UpVar2).  The destination
     variable name is specified in a single string;  it  may  not
     be an array element.

     Both procedures return either TCL_OK or TCL_ERROR, and  they
     leave an error message in interp->result if an error occurs.

     As with the upvar command,  the  source  variable  need  not
     exist; if it does exist, unsetting it later does not destroy
     the link.  The destination variable may exist at the time of
     the call, but if so it must exist as a linked variable.



KEYWORDS

     linked variable, upvar, variable