1 10/17/84  value_set, vs
  2 
  3 Syntax as a command:  vs {name} {value_string} {-control_args}
  4 
  5 
  6 Syntax as an active function:
  7    [vs {name} {value_string} {-control_args}]
  8 
  9 
 10 Function: associates a character string name with a character string
 11 value.  The value replaces any previous value for name.
 12 
 13 
 14 Arguments:
 15 name
 16    is a character string.  It can be -name STR to specify a name
 17    beginning with a minus sign, to distinguish it from a control
 18    argument.  There is no restriction on the length of the name.
 19 value_string
 20    is a character string value, quoted if it contains blanks or other
 21    special characters.  It can be -value STR to specify a value STR
 22    that begins with a minus sign, to distinguish it from a control
 23    argument.  There is no restriction on the length of the value.
 24 
 25 
 26 Control arguments:
 27 -add N
 28    adds N to the integer value of each name selected by the other
 29    control arguments.  If any of the names has no value or has a value
 30    that is not the character string representation of an integer, an
 31    error occurs.  N can be negative or zero, as can be the resulting
 32    value.
 33 -exclude STR, -ex STR
 34    changes all existing associations except those for names that match
 35    STR.  If STR is surrounded by slashes (/), it is interpreted as a
 36    qedx regular expression to match names; otherwise, it is interpreted
 37    as a starname.  Only per-process associations are changed if you
 38    select -perprocess, only permanent ones if you supply -permanent,
 39    and both are changed by default.  (See "Notes.")
 40 
 41 
 42 -if VALUE_STR
 43    sets value_string only if an old value exists and is equal to
 44    VALUE_STR, otherwise returns an error.  If you also specify -match
 45    and/or -exclude, all selected names with current values equal to
 46    VALUE_STR are set to value_string.
 47 -match STR
 48    changes all existing associations for names that match STR.  If STR
 49    is surrounded by slashes, it is interpreted as a qedx regular
 50    expression to match names; otherwise, it is interpreted as a
 51    starname.  Only per-process associations are changed if you select
 52    -perprocess, only permanent ones if you supply -permanent, and both
 53    are changed by default.  (See "Notes.")
 54 -pathname path, -pn path
 55    specifies a value segment other than the current default one,
 56    without changing the default (see "Notes on value segment").
 57 
 58 
 59 -permanent, -perm
 60    sets a value in the value segment, regardless of whether any old
 61    value is per process or permanent.  The default is to change any
 62    existing per-process value, otherwise to change the permanent value
 63    if one exists, otherwise to set a permanent value.
 64 -perprocess, -pp
 65    sets a per-process value, regardless of whether any old value is per
 66    process or permanent.
 67 -pop
 68    restores the previous value, saved by an invocation of "value_set
 69    -push", for each variable specified on the command line.  If any
 70    given variable lacks a previous value, an error message is printed
 71    and the other variables' values are still popped.  This control
 72    argument is incompatible with specifying a value and with -push.
 73 
 74 
 75 -push
 76    saves the old value of each variable before setting the value
 77    specified.
 78 -update, -ud
 79    makes the active function return the previous value or null string
 80    if there is no previous value.  (Default: return the value that is
 81    set)
 82 
 83 
 84 Access required: You need rw access on the value segment except for
 85 per-process values.
 86 
 87 
 88 Notes: You must give one of value_string, -value STR, -add, or -pop.
 89 
 90 The -match and -exclude control arguments are applied in the order
 91 specified.  Successive -match control arguments add to the set of names
 92 processed (union), and successive -exclude control arguments narrow
 93 down the set (intersection).  They are incompatible with the name
 94 argument and can appear multiple times together.  (See "Examples.") You
 95 can't use either -match or -exclude in the active function.
 96 
 97 If you supply -perprocess or the old value is a per-process one, the
 98 value set is per process; otherwise, the association is stored in a
 99 value segment (see "Notes on value segment").  Per-process values are
100 stored in a temporary value segment in the process directory and
101 disappear when the process terminates.
102 
103 
104 When a value is set in a value segment that does not exist, you are
105 asked whether to create the segment.  Your default value segment
106 [hd]>[user name].value is created automatically and a message is
107 printed.
108 
109 See value_defined, value_delete, value_get, value_list, value_path, and
110 value_set_path.
111 
112 
113 Notes on value segment: The value segment searched is either the one
114 specified by -pathname or the current default value segment.  The
115 default segment is initially
116    [home_dir]>[user name].value
117 but you can change it by value_set_path.  Use of -pathname does not
118 change the default segment.