home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / SetVar.3 < prev    next >
Encoding:
Text File  |  1995-07-26  |  10.5 KB  |  199 lines
  1.  
  2.  
  3.  
  4.      TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333))))               TTTTccccllll ((((7777....0000))))               TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           Tcl_SetVar,    Tcl_SetVar2,     Tcl_GetVar,     Tcl_GetVar2,
  12.           Tcl_UnsetVar, Tcl_UnsetVar2 - manipulate Tcl variables
  13.  
  14.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.           ####iiiinnnncccclllluuuuddddeeee <<<<ttttccccllll....hhhh>>>>
  16.  
  17.           char *
  18.           TTTTccccllll____SSSSeeeettttVVVVaaaarrrr(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _n_e_w_V_a_l_u_e, _f_l_a_g_s)
  19.  
  20.           char *
  21.           TTTTccccllll____SSSSeeeettttVVVVaaaarrrr2222(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _n_e_w_V_a_l_u_e, _f_l_a_g_s)
  22.  
  23.           char *
  24.           TTTTccccllll____GGGGeeeettttVVVVaaaarrrr(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _f_l_a_g_s)
  25.  
  26.           char *
  27.           TTTTccccllll____GGGGeeeettttVVVVaaaarrrr2222(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _f_l_a_g_s)
  28.  
  29.           int
  30.           TTTTccccllll____UUUUnnnnsssseeeettttVVVVaaaarrrr(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _f_l_a_g_s)
  31.  
  32.           int
  33.           TTTTccccllll____UUUUnnnnsssseeeettttVVVVaaaarrrr2222(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _f_l_a_g_s)
  34.  
  35.      AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  36.           Tcl_Interp   *_i_n_t_e_r_p     (in)      Interpreter    containing
  37.                                              variable.
  38.  
  39.           char         *_v_a_r_N_a_m_e    (in)      Name  of  variable.   May
  40.                                              refer    to    a   scalar
  41.                                              variable or an element of
  42.                                              an array variable.
  43.  
  44.           char         *_n_e_w_V_a_l_u_e   (in)      New value for variable.
  45.  
  46.           int          _f_l_a_g_s       (in)      OR-ed combination of bits
  47.                                              providing      additional
  48.                                              information           for
  49.                                              operation.  See below for
  50.                                              valid values.
  51.  
  52.           char         *_n_a_m_e_1      (in)      Name of scalar  variable,
  53.                                              or name of array variable
  54.                                              if _n_a_m_e_2 is non-NULL.
  55.  
  56.           char         *_n_a_m_e_2      (in)      If non-NULL,  gives  name
  57.                                              of  element  within array
  58.                                              and _n_a_m_e_1 must  refer  to
  59.                                              an array variable.
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/10/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333))))               TTTTccccllll ((((7777....0000))))               TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333))))
  71.  
  72.  
  73.  
  74.      _________________________________________________________________
  75.  
  76.  
  77.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  78.           These procedures may be used to create,  modify,  read,  and
  79.           delete   Tcl   variables   from   C  code.   TTTTccccllll____SSSSeeeettttVVVVaaaarrrr  and
  80.           TTTTccccllll____SSSSeeeettttVVVVaaaarrrr2222 will create a new variable or modify an existing
  81.           one.  Both of these procedures set the given variable to the
  82.           value given by _n_e_w_V_a_l_u_e, and they return a pointer to a copy
  83.           of  the  variable's  new  value,  which  is  stored in Tcl's
  84.           variable  structure.   Tcl  keeps  a  private  copy  of  the
  85.           variable's  value,  so  the caller may change _n_e_w_V_a_l_u_e after
  86.           these procedures return without affecting the value  of  the
  87.           variable.   If an error occurs in setting the variable (e.g.
  88.           an array variable is referenced without giving an index into
  89.           the array), then NULL is returned.
  90.  
  91.           The name of the variable may be specified in either  of  two
  92.           ways.   If  TTTTccccllll____SSSSeeeettttVVVVaaaarrrr is called, the variable name is given
  93.           as a single string, _v_a_r_N_a_m_e.  If _v_a_r_N_a_m_e  contains  an  open
  94.           parenthesis  and  ends  with  a  close parenthesis, then the
  95.           value between the parentheses is treated as an index  (which
  96.           can  have  any  string  value) and the characters before the
  97.           first open parenthesis are treated as the name of  an  array
  98.           variable.   If _v_a_r_N_a_m_e doesn't have parentheses as described
  99.           above, then the entire string is treated as the  name  of  a
  100.           scalar  variable.   If TTTTccccllll____SSSSeeeettttVVVVaaaarrrr2222 is called, then the array
  101.           name and index have been separated by the  caller  into  two
  102.           separate strings, _n_a_m_e_1 and _n_a_m_e_2 respectively;  if _n_a_m_e_2 is
  103.           zero it means that a scalar variable is being referenced.
  104.  
  105.           The _f_l_a_g_s argument may be used to  specify  any  of  several
  106.           options   to  the  procedures.   It  consists  of  an  OR-ed
  107.           combination of any of the following bits:
  108.  
  109.           TCL_GLOBAL_ONLY
  110.                Under  normal  circumstances  the  procedures  look  up
  111.                variables  at  the  current level of procedure call for
  112.                _i_n_t_e_r_p, or at global level if there is no call  active.
  113.                However,  if this bit is set in _f_l_a_g_s then the variable
  114.                is looked up  at  global  level  even  if  there  is  a
  115.                procedure call active.
  116.  
  117.           TCL_LEAVE_ERR_MSG
  118.                If an error is returned and this bit is set  in  _f_l_a_g_s,
  119.                then  an  error message will be left in _i_n_t_e_r_p->_r_e_s_u_l_t.
  120.                If this flag bit isn't set then  no  error  message  is
  121.                left (_i_n_t_e_r_p->_r_e_s_u_l_t will not be modified).
  122.  
  123.           TCL_APPEND_VALUE
  124.                If this bit is set then _n_e_w_V_a_l_u_e  is  appended  to  the
  125.                current   value,  instead  of  replacing  it.   If  the
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/10/95)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333))))               TTTTccccllll ((((7777....0000))))               TTTTccccllll____SSSSeeeettttVVVVaaaarrrr((((3333))))
  137.  
  138.  
  139.  
  140.                variable is  currently  undefined,  then  this  bit  is
  141.                ignored.
  142.  
  143.           TCL_LIST_ELEMENT
  144.                If this bit is set, then _n_e_w_V_a_l_u_e  is  converted  to  a
  145.                valid Tcl list element before setting (or appending to)
  146.                the variable.  A separator space is appended before the
  147.                new list element unless the list element is going to be  |
  148.                the first element  in  a  list  or  sublist  (i.e.  the  |
  149.                variable's  current  value  is  empty,  or contains the  |
  150.                single character ``{'', or ends in `` }'').
  151.  
  152.           TTTTccccllll____GGGGeeeettttVVVVaaaarrrr and TTTTccccllll____GGGGeeeettttVVVVaaaarrrr2222 return the  current  value  of  a
  153.           variable.   The arguments to these procedures are treated in
  154.           the same way as the arguments to TTTTccccllll____SSSSeeeettttVVVVaaaarrrr and TTTTccccllll____SSSSeeeettttVVVVaaaarrrr2222.
  155.           Under normal circumstances, the return value is a pointer to
  156.           the variable's value (which  is  stored  in  Tcl's  variable
  157.           structure  and  will  not  change  before  the  next call to
  158.           TTTTccccllll____SSSSeeeettttVVVVaaaarrrr or TTTTccccllll____SSSSeeeettttVVVVaaaarrrr2222).  The only bits of _f_l_a_g_s that are
  159.           used  are  TCL_GLOBAL_ONLY  and  TCL_LEAVE_ERR_MSG,  both of
  160.           which have the same meaning as for TTTTccccllll____SSSSeeeettttVVVVaaaarrrr.  If an  error
  161.           occurs  in  reading  the variable (e.g. the variable doesn't
  162.           exist  or  an  array  element  is  specified  for  a  scalar
  163.           variable), then NULL is returned.
  164.  
  165.           TTTTccccllll____UUUUnnnnsssseeeettttVVVVaaaarrrr and TTTTccccllll____UUUUnnnnsssseeeettttVVVVaaaarrrr2222  may  be  used  to  remove  a
  166.           variable,  so that future calls to TTTTccccllll____GGGGeeeettttVVVVaaaarrrr or TTTTccccllll____GGGGeeeettttVVVVaaaarrrr2222
  167.           for the variable will return an  error.   The  arguments  to
  168.           these  procedures  are  treated  in  the  same  way  as  the
  169.           arguments to TTTTccccllll____GGGGeeeettttVVVVaaaarrrr and TTTTccccllll____GGGGeeeettttVVVVaaaarrrr2222.  If the variable is  |
  170.           successfully  removed  then  TCL_OK  is  returned.   If  the  |
  171.           variable cannot be removed because  it  doesn't  exist  then  |
  172.           TCL_ERROR  is  returned.   If an array element is specified,
  173.           the given element is removed but the array remains.   If  an
  174.           array  name  is  specified without an index, then the entire
  175.           array is removed.
  176.  
  177.  
  178.      SSSSEEEEEEEE AAAALLLLSSSSOOOO
  179.           Tcl_TraceVar
  180.  
  181.  
  182.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  183.           array, interpreter, scalar, set, unset, variable
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 7/10/95)
  196.  
  197.  
  198.  
  199.