1 05/16/88  value_get, vg
 2 
 3 Syntax as a command:  vg name {-control_args}
 4 
 5 
 6 Syntax as an active function:  [vg name {-control_args}]
 7 
 8 
 9 Function: returns the character string value of a name, as set by
10 value_set.  If the name has no value and you choose -default, an error
11 occurs.  Values, except for per-process values, are stored in a value
12 segment with suffix "value" (see "Notes on value segment").
13 
14 
15 Arguments:
16 name
17    is a character string.  It can be -name STR to specify a name
18    beginning with a minus sign, to distinguish it from a control
19    argument.
20 
21 
22 Control arguments:
23 -call STR
24    if no value is found for name, the active function [STR] is expanded
25    to produce a value, which is both set for name and returned.
26    Enclose STR in quotes and omit the brackets if it contains special
27    characters such as spaces.  This control argument is incompatible
28    with -default.
29 -data
30    specifies that the value of the name is actually an uninterpreted
31    data region, normally accessable by using the value_$set_data and
32    value_$get_data subroutine interface.  The contents of the region
33    will be returned in an uninterpreted form.  See "Notes on data-type
34    values".
35 
36 
37 -default STR, -df STR
38    specifies a default value to be returned if none is set.  Enclose
39    STR in quotes if it contains special characters.  A null string is
40    returned if STR is "".  If you don't give -default and no value
41    exists, an error occurs.
42 -pathname path, -pn path
43    specifies a value segment other than the current default one,
44    without changing the default (see "Notes on value segment").  It is
45    incompatible with -perprocess.
46 
47 
48 -permanent, -perm
49    does not look for a per-process value.  The default is to return the
50    per-process value if one exists, otherwise to return the value
51    stored in the value segment; if none exists, an error occurs.
52 -perprocess, -pp
53    looks only for a per-process value, not for one stored in any value
54    segment.  If a per-process value is not found, an error occurs.
55 -pop
56    deletes the current value that it prints or returns.  If a previous
57    value was saved by value_set -push, that value is reinstated.
58 
59 
60 Access required: You require read access on the value segment, except
61 for per-process values.
62 
63 
64 Notes: Per-process values are stored in a temporary value segment in
65 the process directory and disappear when the process terminates.
66 
67 By default, both "vg name" and "vg name -pn path" return the
68 per-process value of name if there is one; otherwise, they return the
69 value stored in the appropriate value segment.  By contrast, "vg -pp"
70 returns only the per-process value, and "vg -perm" returns only the one
71 in the value segment.
72 
73 See value_defined, value_delete, value_list, value_path, value_set, and
74 value_set_path.
75 
76 
77 Notes on data-type values:  The contents of data-type values are
78 normally used to hold data structure information, which contain
79 non-ascii (binary) information.  If the -data argument is used,
80 the value of the named data-type element will be returned with no
81 conversion performed.  It is suggested that the output be routed
82 into a temporary segment by using the file_output command or
83 the I/O redirection facility of the command processor (;|).
84 
85 The -data control argument is incompatible with the -call, -default,
86 pop or -perprocess control arguments.
87 
88 
89 Notes on value segment: The value segment searched is either the one
90 specified by -pathname or the current default value segment.  The
91 default segment is initially
92    [home_dir]>[user name].value
93 but you can change it by value_set_path.  Use of -pathname does not
94 change the default segment.