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.


 PREV   NEXT