2.4.1 The ADDRESS Instruction ADDRESS [ environment [ command ] ] ; [ [ VALUE ] expression ] ; The ADDRESS instruction controls where commands to external environment are sent. If both environment and command are specified, the given command will be executed in the given environment. The effect is the same as issuing an expression to be executed as a command (see section Commands), except that the environment in which it is to be executed can be explicitly specified in the ADDRESS clause. In this case, the special variable RC will be set as usual, and the ERROR or FAILURE conditions might be raised, as for normal commands. The environment term must be a symbol or a literal string. If it is a symbol, its “name” is used, i.e. it is not tail substituted or swapped for a variable value. The command and expression terms can be any REXX expression. REXX maintains a list of environments, the size of this list is at least two. If you select a new environment, it will be put in the front of this list, possibly squeezing the backend environment out of the list. Note that if command is specified, the contents of the environment stack is not changed. If you omit command, environment will always be put in the front of the list of environments. What happens if you specify an environment that is already in the list, is not completely defined. Strictly speaking, you should end up with both entries in the list pointing to the same environment, but some implementations will probably handle this by reordering the list, leaving the selected environment in the front. If you do not specify any subkeywords or parameters to ADDRESS, the effect is to swap the two first entries in the list of environments. Consequently, executing ADDRESS multiple times will toggle between two environments. The second syntax form of ADDRESS is a special case of the first form with command omitted. If the first token after ADDRESS is VALUE, then the rest of the clause is taken to be an expression, naming the environment which is to be made the current environment. Using VALUE makes it possible to circumvent the restriction that the name of the new environment must be a symbol or literal string. However, you can not combine both VALUE and command in a single clause. Example: Examples of the ADDRESS instruction You can omit the VALUE keyword if the expression following ADDRESS starts with a token which is neither a symbol or a literal string. Confused? Let’s look at some examples: ADDRESS COMMAND ADDRESS SYSTEM ‘copy’ fromfile tofile ADDRESS system ADDRESS VALUE newenv ADDRESS ADDRESS (oldenv) The first of these sets the environment COMMAND as the current environment. The second performs the command copy in the environment SYSTEM, using the values of the symbols fromfile and tofile as parameters. Note that this will not set SYSTEM as current environment. The third example sets SYSTEM as current environment (it will be automatically converted to upper case). The fourth example sets as the current environment the contents of the symbol newenv, pushing SYSTEM down one level in the stack. The fifth clause swap the two uppermost entries on the stack; and SYSTEM ends up at the top. The last example sets the current environment to whatever is the value of the symbol oldenv. Example: The VALUE subkeyword Let us look a bit closer at the last example. Note the differences between the two clauses: ADDRESS OLDENV ADDRESS (OLDENV) The first of these sets the current default environment to OLDENV, while the second sets it to the value of the symbol OLDENV. Actually, in the latter, the subkeyword VALUE has been omitted, which is legal since the parameter starts with a special character. If you are still confused, Don’t Panic; the syntax of ADDRESS is somewhat bizarre, and you should not put too much effort into learning all aspects of it. Just make sure that you understand how to use it in simple situations. Chances are that you will not have use for its more complicated variants for quite some time. Then, what names are legal as environments? Well, that is implementation-specific, but some names seems to be in common use. The name COMMAND is sometimes used to refer to an environment that sends the command to the operating system. Likewise, the name of the operating system is often used for this (CMS, UNIX, etc.). You have to consult the implementation specific documentation for more information about this. Actually, there is not really any restrictions on what constitutes a legal environment name (even the nullstring is legal). Some interpreters will allow you to select anything as current environment; and if it is an illegal name, the interpreter will complain only when the environment is actually tried used. Other implementations may not allow you to select an invalid environment name at all. Nor does the definition of REXX say anything about which environment is preselected when you invoke the interpreter, although TRL defines that one environment is automatically preselected when starting up a REXX script. Note that there does not exist any NONE environment in standard REXX, i.e. an environment that ignores commands. But some interpreters implement the TRACE setting ??? which accomplish this. The list of environments will be saved across subroutine calls; so the effect of any ADDRESS clauses in the subroutine will cease upon return from the subroutine.