In addition to the special variables, Rexx provides a unique set of objects, called environment objects. Environment objects are members of the Object class only. Rexx makes the following environment objects available:
The Environment object is a directory of public objects that are always accessible throughout the whole process. To place something in the Environment directory, you use the form:
.environment~your.object = value
Include a period (.) in any object name you use, to avoid conflicts with current or future Rexx entries to the Environment directory. To retrieve your object, you use the form:
say .environment~your.objectThe scope of .environment is the current process.
You use an environment symbol to access the entries of this directory. An environment symbol starts with a period and has at least one other character, which must not be a digit. You have seen environment symbols earlier; for example in:
asav = .savings~new
.Savings is an environment symbol, and refers to the Savings class. The classes you create can be referenced with an environment symbol. There is an environment symbol for each Rexx-defined class, as well as for each of the unique objects this section describes, such as the NIL object.
The NIL object is a special environment object that does not contain any data. It represents the absence of an object, the way a null string represents a string with no characters. Its only methods are those of the Object class. You use the NIL object (rather than the null string) to test for the absence of data in an array entry:
if board[row,column] = .nil then ...
All the environment objects Rexx provides are single symbols. Use compound symbols when you create your own, to avoid conflicts with future Rexx-defined entries.
The Local environment object is a directory of process-specific objects that are always accessible. To place something in the Local environment directory, you use the form:
.local~your.object = value
Be sure to include a period (.) in any object name you use, to avoid conflicts with current or future Rexx entries to the Local directory. To retrieve your object, you use the form:
say .local~your.objectThe scope of .local is the current process.
You access objects in the Local environment object like in the Environment object. Rexx provides the following objects in the Local environment:
is the Error object (the default error stream) to which Rexx writes error messages and trace output to.
is the Input object (the default input stream), which is the source for the PARSE LINEIN instruction, the LINEIN method of the Stream class, and (if you do not specify a stream name) the LINEIN built-in function. It is also the source of the PULL and PARSE PULL instructions if the external data queue is empty.
is the Output object (the default output stream), which is the destination of output from the SAY instruction, the LINEOUT method (.OUTPUT~LINEOUT), and (if you do not specify a stream name) the LINEOUT built-in function. You can replace this object in the environment to direct such output elsewhere, for example to a transcript window.
Rexx provides environment objects that all programs can use. To access these built-in objects, you use the special environment symbols whose first character is a period (.).
The .methods environment symbol identifies a directory of methods that ::METHOD directives in the currently running program define. The directory indexes are the method names. The directory values are the method objects. Only methods that are not preceded by a ::CLASS directive are in the .methods directory. If there are no such methods, the .methods symbol has the default value of ".METHODS". Here is an example:
use arg class, methname class~define(methname,.methods["a"]) ::method a use arg text say text
The .line environment symbol returns the line number of the current instruction being executed. If the current instruction is defined within an INTERPRET instruction, the value returned is the line number of INTERPRET instruction.
.rs is set to the return status from any executed command, including those submitted with the ADDRESS instruction. The .rs environment symbol has a value of -1 when a command returns a FAILURE condition, a value of 1 when a command returns an ERROR condition, and a value of 0 when a command indicates successful completion. The value of .rs is also available after trapping the ERROR or FAILURE condition.
Note: Tracing interactively does not change the value of .rs. The initial value of .rs is 0.
When you use an environment symbol, Rexx performs a series of searches to see if the environment symbol has an assigned value. The search locations and their ordering are:
The directory of classes declared on ::CLASS directives within the current program file.
The directory of PUBLIC classes declared on ::CLASS directives of other files included with a ::REQUIRES directive.
The program local environment directory, which includes process-specific objects such as the .INPUT and .OUTPUT objects. You can directly access the local environment directory by using the .Local environment symbol.
The global environment directory, which includes all "permanent" Rexx objects such as the Rexx-supplied classes (for example, .ARRAY) and constants such as .TRUE and .FALSE. You can directly access the global environment by using the .environment symbol or using the VALUE built-in function with a null string for the selector argument.
Rexx defined symbols. Other simple environment symbols are reserved for use by Rexx for built-in objects. The currently defined built-in objects are .RS and .METHODS.
If an entry is not found for an environment symbol, the default character string value is used.
Note: You can place entries in both the .local and .environment directories for programs to use. To avoid conflicts with future Rexx-defined entries, it is recommended that entries you place in either of these directories include at least one period in the entry name.
Example:
/* establish a global settings directory */
.local~setentry("MyProgram.settings", .directory~new)