>>-VALUE(name--+--------------------------------+--)-----------><
+-,--+----------+--+-----------+-+
+-newvalue-+ +-,selector-+
Returns the value of the symbol that
name (often constructed dynamically) represents and optionally assigns a new value to it. By default, VALUE refers to the current Rexx-variables environment, but other, external collections of variables can be selected. If you use the function to refer to Rexx variables,
name must be a valid Rexx symbol. (You can confirm this by using the SYMBOL function.) Lowercase characters in
name are translated to uppercase for the local environment. For the global environment lowercase characters are not translated because the global environment supports mixed-case identifiers. Substitution in a compound name (see
Section 1.13.5, “Compound Symbols”) occurs if possible.
If you specify newvalue, the named variable is assigned this new value. This does not affect the result returned; that is, the function returns the value of name as it was before the new assignment.
Here are some examples:
Example 7.96. Builtin function VALUE
/* After: Drop A3; A33=7; K=3; fred="K"; list.5="Hi" */
VALUE("a"k) -> "A3" /* looks up A3 */
VALUE("a"k||k) -> "7"
VALUE("fred") -> "K" /* looks up FRED */
VALUE(fred) -> "3" /* looks up K */
VALUE(fred,5) -> "3" /* looks up K and */
/* then sets K=5 */
VALUE(fred) -> "5" /* looks up K */
VALUE("LIST."k) -> "Hi" /* looks up LIST.5 */
To use VALUE to manipulate environment variables, selector must be the string "ENVIRONMENT" or an expression that evaluates to "ENVIRONMENT". In this case, the variable name need not be a valid Rexx symbol. Environment variables set by VALUE are not kept after program termination.
Restriction: The values assigned to the variables must not contain any character that is a hexadecimal zero ("00"X). For example:
Call VALUE "MYVAR", "FIRST" || "00"X || "SECOND", "ENVIRONMENT"
sets MYVAR to "FIRST", truncating "00"x and "SECOND".
Here are some more examples:
Example 7.97. Builtin function VALUE
/* Given that an external variable FRED has a value of 4 */
share = "ENVIRONMENT"
say VALUE("fred",7,share) /* says "4" and assigns */
/* FRED a new value of 7 */
say VALUE("fred", ,share) /* says "7" */
/* Accessing and changing Windows environment entries given that */
/* PATH=C:\EDIT\DOCS; */
env = "ENVIRONMENT"
new = "C:\EDIT\DOCS;"
say value("PATH",new,env) /* says "C:\WINDOWS" (perhaps) */
/* and sets PATH = "C:\EDIT\DOCS;" */
say value("PATH", ,env) /* says "C:\EDIT\DOCS;" */
To delete an environment variable use the Nil object as the newvalue. To delete the environment variable "MYVAR" specify: value("MYVAR", .NIL, "ENVIRONMENT"). If you specify an empty string as the newvalue like in value("MYVAR", "", "ENVIRONMENT") the value of the external environment variable is set to an empty string which on Windows and *nix is not the same as deleting the environment variable.
A selector called "WSHENGINE" is also available to the VALUE function when a Rexx script is run in a Windows Script Host scripting context (running via cscript, wscript or as embedded code in HTML for the Microsoft Internet Explorer). The only currently supported value is "NAMEDITEMS". Calling VALUE with these parameters returns an array with the names of the named items that were added at script start.
Example:
myArray = VALUE("NAMEDITEMS", ,"WSHENGINE")
The value NAMEDITEMS is read-only, writing to it is prohibited.
Object Rexx scripts running via the scripting engine (in WSH context) can now call the default method of an object as a function call with the object name.
Example:
The SESSION object of ASP (Active Server Pages) has the default method VALUE. The usual (and recommended) way of using the SESSION object would be to use
SESSION~VALUE("key","value").
Because VALUE is the default method, a function call
SESSION("key","value")
SESSION~VALUE("key","value").
causes an invocation of VALUE with the given arguments. For objects that have the name of a Rexx function, an explicit call to the default method must be made, because Rexx functions have priority over this implicit method invocation mechanism.
In contrast to OS/2, the Windows and *nix environments are unchanged after program termination.
You can use the VALUE function to return a value to the global environment directory. To do so, omit
newvalue and specify
selector as the null string. The language processor sends the message
name (without arguments) to the current environment object. The environment returns the object identified by
name. If there is no such object, it returns, by default, the string
name with an added initial period (an environment symbol--see
Section 1.13.6, “Environment Symbols”).
Here are some examples:
Example 7.98. Builtin function VALUE
/* Assume the environment name MYNAME identifies the string "Simon" */
name = value("MYNAME", ,"") /* Sends MYNAME message to the environment */
name = .myname /* Same as previous instruction */
say "Hello," name /* Produces: "Hello, Simon" */
/* Assume the environment name NONAME does not exist. */
name = value("NONAME", ,"") /* Sends NONAME message to the environment */
say "Hello," name /* Produces: "Hello, .NONAME" */
You can use the VALUE function to change a value in the Rexx environment directory. Include a newvalue and specify selector as the null string. The language processor sends the message name (with = appended) and the single argument newvalue to the current environment object. After receiving this message, the environment identifies the object newvalue by the name name.
Here is an example:
Example 7.99. Builtin function VALUE
name = value("MYNAME","David","") /* Sends "MYNAME=("David") message */
/* to the environment. */
/* You could also use: */
/* call value "MYNAME","David","" */
say "Hello," .myname /* Produces: "Hello, David" */
Notes:
If the VALUE function refers to an uninitialized Rexx variable, the default value of the variable is always returned. The NOVALUE condition
is not raised because a reference to an external collection of variables never raises NOVALUE.
The VALUE function is used when a variable contains the name of another variable, or when a name is constructed dynamically. If you specify
name as a single literal string and omit
newvalue and
selector, the symbol is a constant and the string between the quotation marks can usually replace the whole function call. For example,
fred=VALUE("k"); is identical with the assignment
fred=k;, unless the NOVALUE condition is trapped. See
Chapter 11, Conditions and Condition Traps.
