%
%  The Regina Rexx Interpreter
%  Copyright (C) 1992-1994  Anders Christensen <anders@pvv.unit.no>
%


\newenvironment{syntax}{\smallskip\setlength{\parskip}{0mm}\tt}{}


\chapter{Clauses, Statements, and Instructions}

\begin{it}
   In this chapter, the concept and syntax of {\rexx} clauses are
   explained. At the end of the chapter there is a section describing
   how {\regina} differs from standard\/ {\rexx} are described in the
   first part of the chapter.
\end{it}


\section{Definitions}

A program in the {\rexx} language consists of clauses, which are
divided into four groups: null clauses, commands, assignments, and
instructions. The three latter groups (commands, assignments, and
instructions) are collectively refered to as statements. This does not
match the terminology in \cite{trl2}, where ``instruction'' is
equivalent to what is known here as ``statement'', and ``keyword
instruction'' is equivalent to what is known here as ``instruction''.
However, I find the terminology used here simpler and less confusing.
Incidently, the terminology used here matches e.g.\ {\cite{daney}}.

A clause is defined as all non-clause-delimitors (i.e.\ blanks and
tokens) up to and including a clause delimitor. A token delimitor can
be:
\begin{itemize}
\item
   An end-of-line, unless it lies within a comment. An end-of-line
   within a constant string is considered a syntax error
   {\syntaxerror{6}}.

\item
   A semicolon character that is not within a comment or constant
   string.

\item
   A colon character, provided that the sequence of tokens leading up
   to it consists of a single symbol and whitespace. If a sequence of
   two symbol tokens is followed by a colon, then this implies {\tt
   SYNTAX} condition {\syntaxerror{13}}.
\end{itemize}
Some systems have the ability to store a text file having a last line
unterminated by an end-of-line character sequence. In general, this
applies to systems that use an explicit end-of-line character sequence
to denote end-of-lines, e.g.\ Unix and MS-DOS systems. Under these
systems, if the last line is unterminated, it will strictly speaking
not be a clause, since a clause must include its terminating clause
delimitor.  However, some interpreters are likely to regard the
end-of-file as a clause delimitor too. The functionality of {\tt
INTERPRET} gives some weight to this interpretation. But other systems
may ignore that last, unterminated line, or maybe issue a syntax
error. (However, there are no {\tt SYNTAX} condition number adequately
covering this situation.
\begin{example}[Binary transferring files]
Suppose a {\rexx} program is stored on an MS-DOS machine. Then, an
end-of-line sequence is marked in the file as the two characters
carriage return and newline. If this file is transferred to a Unix
system, then only newline marks the end-of-line. For this to work, the
file must be transferred as a text file. If it is (incorrectly)
transferred as a binary file, the result is that on the Unix system,
each line seems to contain a trailing carriage return character. In an
editor, it might look like this:
\begin{quote}\tt
   say 'hello world'\verb|^M|\\
   say 'that''s it'\verb|^M|
\end{quote}
This will probably raise {\tt SYNTAX} condition {\syntaxerror{13}}. 
\end{example}


\section{Null clauses}

Null clauses are clauses that consist of only whitespace, or comments,
or both; in addition to the terminating clause delimitor.  These
clauses are ignored when interpreting the code, except for one
situation: null clauses containing at least one comment is traced when
appropriate.  Null clauses not containing any comments are ignored in
every respect.

\begin{example}[Tracing comments]
The tracing of comments may be a major problem, depending on the
context. There are basically two strategies for large comments: either
box multiple lines as a single comment, or make the text on each line
an independant comment, as shown below:
\begin{quote}
\begin{verbatim}
trace all
/*
 * This is a single, large comment, which spans multiple lines.
 * Such comments are often used at the start of a subroutine or
 * similar, in order to describe both the interface to and the
 * functionality of the function.
 */

/* This is also a large comment, but it is written as multiple   */
/* comments, each on its own line. Thus, this is several clauses */
/* while the comment above is a single comment.                  */
\end{verbatim}
\end{quote}
During tracing, the first of these will be displayed as one large
comment, and during interactive tracing, it will only pause once. The
second will be displayed as muliple lines, and will make several
pauses during interactive tracing. An interpreter may solve this
situation in several ways, the main objective must be to display the
comments nicely the the programmer debugging the code.  Preferably,
the code is shown in a fashion that resembles how it is entered in the
file.
\end{example}

If a label is multiple defined, the first definition is used and the
rest are ignored. Multiple defined labels is not an {\tt SYNTAX}
condition. 

A null clause is not a statement. In some situations, like after the
{\tt THEN} subclause, only a statement come. If a null clause is
provided, then it is ignored, and the next statement is used instead.
Consider the following code:
\begin{quote}\tt
\begin{tabbing}
XXX\=\kill
	parse pull foo\\
	if foo=2 then\\
\>	   say 'foo is not 2'\\
	else\\
\>	   /* do nothing */\\
	say 'that''s it'
\end{tabbing}
\end{quote}
This will not work the way indentation indicates, since the comment in
this example is not a statement. Thus, the {\tt ELSE} reads beyond the
comment, and connects to the {\tt SAY} instruction which becomes the
{\tt ELSE} part. (That what probably not what the programmer
intended.)  This code will say {\tt that's it}, only when {\tt foo} is
different from {\tt 2}.  A separate instruction, {\tt NOP} has been
provided in order to fill the need that was inadequately attempted
filled by the comment in the code fragment above.

\begin{example}[Trailing comments]
The effect that comments are not statements can be exploited when
documenting the program, and simultaneoutly making the program
faster. Consider the following two loops:
\begin{quote}
\begin{verbatim}
sum = 0
do i=1 to 10
   /* sum 1 2 3 ... 8 9 10 */
   sum = sum + i 
   end 

sum = 0
do i=1 to 10
   sum = sum + i   /* sum 1 2 3 ... 8 9 10 */
   end
\end{verbatim}
\end{quote}

In the first loop, there are two clauses, while the second loop
contains only one clause, because the comment is appended to an
already existing clause. During execution, the interpreter has to
spend time ignoring the null clause in the first loop, while the
second loop avoids this problem (assuming tracing is disenabled).
Thus, the second loop is faster; although only insignificantly faster
for small loops. Of course, the comment could have been taken out of
the loop, which would be equally fast to the second version above.
\end{example}


\section{Commands}
\label{sec:commands}

\section{Assignments}
\label{sect:assign}

Assignments are clauses where the first token is a symbol and the
second token is the equal sign ({\tt =}). This definition opens for some
curious effects, consider the following clauses:
\begin{description}
\item[\tt a == b]\hfill\\
   This is not a command, but an assignment of the expression {\tt =
   b} to the variable {\tt a}. Of course, the expression is illegal
   ({\tt =b}) and will trigger a {\tt SYNTAX} condition for syntax
   error \syntaxerror{35}. TRL2 defines the operator {\tt ==} as
   consisting of two tokens. Thus, in the first of these examples, the
   second token is {\tt =}, the third token is also {\tt =}, while the
   fourth token is {\tt b}.

\item[\tt 3 = 5]\hfill\\
   This is an assignment of the value {\tt 5} to the symbol {\tt 3},
   but since this is not a variable symbol, this is an illegal
   assignment, and will trigger the {\tt SYNTAX} condition for syntax
   error \syntaxerror{31}.

\item[\tt "hello" = foo]\hfill\\
   This is not an invalid assignment, since the first token in the
   clause is not a symbol. Instead, this becomes a command.

\item[\tt arg =(foo) bar]\hfill\\
   The fourth statement is a valid assignment, which will
   space-concatenate the two variable symbols {\tt foo} and {\tt bar},
   and assign the result to the variable symbol {\tt arg}. It is
   specifically not an {\tt ARG} instruction, even though it might
   look like one. If you need an {\tt ARG} instruction which template
   starts with an absolute indirect positional pattern, use the {\tt
   PARSE UPPER ARG} instruction instead, or prepend a dot in front of
   the template.
\end{description}

An assignment can assign a value to a simple variable, a stem variable
or a compound variable. When assigning to a stem variable, all
possible variable symbols having that stem are assigned the value.
Note specifically that this is not like setting a default, it is a one
time multiple assignment. 

\begin{example}[Multiple assignment]
The difference between {\rexx}'s multiple assignment and a default
value can be seen from the following code:
\begin{quote}
\begin{verbatim}
foo. = 'bar'
foo.1 = 'baz'
drop foo.1
say foo.1        /* says "FOO.1" */
\end{verbatim}
\end{quote}
Here, the {\tt SAY} instruction writes out\/ {\tt FOO.1}, not\/ {\tt
bar}.  During the {\tt DROP} instruction, the variable {\tt FOO.1}
regains its original, uninitialized value {\tt FOO.1}, not the value
of its stem variable {\tt FOO.}, i.e.\ {\tt bar}, because stem
assignments does not set up a default.
\end{example}

\begin{example}[Emulating a default value]
If you want to set the compound variable to the value of its stem
variable, if the stem is initialized, then you may use the following
code:
\begin{quote}
\begin{verbatim}
if (symbol('foo.')) then
   foo.1 = foo.
else
   drop foo.1
\end{verbatim}
\end{quote}
In this example, the {\tt FOO.1} variable is set to the value of its
stem if the stem currently is assigned a value. Else, the {\tt FOO.1}
variable is dropped. 

However, this is probably not exactly the same, since the internal
storage of the computer is likely to store variables like {\tt FOO.2}
and {\tt FOO.3} only implicitly (after all, it can not explicitly
store every compound having {\tt FOO.\@} as stem). After the assignment
of the value of\/ {\tt FOO.\@} to {\tt FOO.1}, the {\tt FOO.1} compound
variable is likely to be explicitly stored in the interpreter. 

There is no way you can discover the difference, but the effects are
often that more memory is used, and some functionality that dumps all
variables may dump {\tt FOO.1} but not {\tt FOO.2} (which is
inconsistent). See section \ref{fn:RexxVarPool}.
\end{example}

\begin{example}[Space considerations]
Even more strange are the effects of the following short example:
\begin{quote}
\begin{verbatim}
foo. = 'bar'
drop foo.1
\end{verbatim}
\end{quote}
Although appearantly very simple, there is no way that an interpreter
can release all memory refering to {\tt FOO.1}. After all, {\tt FOO.1}
has a different value than {\tt FOO.2}, {\tt FOO.3}, etc, so the
interpreter must store informatation that tells it that\/ {\tt FOO.1} has
the uninitialized value. 

These considerations may seem like nitpicking, but they will matter if
you drop lots of compound variables for a stem which has previously
received a value. Some programming idioms do this, so be aware. If
you can do without assigning to the stem variable, then it is possible
for the interpreter to regain all memory used for that stem's compound
variables. 
\end{example}


% bar = 1
% foo.bar = value('foo',2)
% say foo.1 foo.2   /* 1 FOO.2   eller    FOO.1 1 */





\section{Instructions}

In this section, all instructions in standard {\rexx} are described.
Extensions are listed later in this chapter. 

First some notes on the terminology. What is called an instruction in
this document is equivalent to a ``unit'' of clauses. That is, each
instruction can consist of one or more clauses. For instance, the {\tt
SAY} instruction is always a single instruction, but the {\tt IF}
instruction is a multi-clause instruciton. Consider the following
script, where each clause has been boxed:
\begin{quote}
\begin{tabbing}
XXX\=\kill
   \fbox{\tt if a=b} \fbox{\tt then}\\
\>    \fbox{\tt say 'hello'}\\
   \fbox{\tt else}\\
\>    \fbox{\tt say 'bye'}\\
\end{tabbing}
\end{quote}
Further, the {\tt THEN} or {\tt ELSE} parts of this instruction might
consist of a {\tt DO}/{\tt END} pair, in which case the {\tt IF}
instruction might consists of an virtually unlimited number of
clauses. 

Then, some notes on the syntax diagrams used in the following
descriptions of the instructions. The rules applying to these diagrams
can be listed as:
\begin{itemize}
\item 
   Anything written in {\tt courier} font in the syntax diagrams
   indicates that it should occur as-is in the {\rexx} program.
   Whenever something is written in {\it italic} font, it means that
   the term should be substituted for another value, expression, or
   terms. 

\item
   Anything contained within matching pairs of square brackets ([...])
   are optional, and may be left out. 

\item
   Whenever a pair or curly braces is used, it contains two or more
   subclauses that are separated by the vertical bar ({\tt |}). It
   means that the curly braces will be substitued for one of the
   subclauses it contains. 

\item
   Whenever the ellipsis (...) is used, it indicates that the
   immediately following subclauses may be repeated zero or more
   times. The scope of the ellipsis is limited to the contents of a
   set of square brackets or curly braces, if it occurs there.

\item
   Whenever the vertical bar {\tt |} is used in any of the syntax
   diagrams, it means that either the term to the left, or the term to
   the right can be used, but not both, and at least one of the must
   be used.  This ``operator'' is assiciative (can be used in
   sequence), and it has lower priority than the square brackets (the
   scope of the vertical bar located within a pair of square brackets
   or curly braces is limited to the text within those square brackets
   or curly braces.

\item
   Whenever a semicolon ({\tt ;}) is used in the syntax diagram, it
   indictates that a clause separator must be present at the point. It
   may either be a semicolon character, or an end-of-line.

\item
   Whenever the syntax diagram is spread out over more lines, it means
   that any of the lines can be used, but that the individual lines
   are mutally exclusive. Consider the syntax:
\begin{quote}\tt
\begin{tabbing}
   SAY \= {\it symbol}\\
       \> {\it string}
\end{tabbing}
\end{quote}
   This is equivalent to the syntax:
\begin{quote}
   {\tt SAY} [ {\it symbol} {\tt |} {\it string} ]
\end{quote}
   Because in the first of these two syntaxes, the {\tt SAY} part may
   be continued at either line.

\item
   Sometimes the syntax of an instruction is so complex that parts of
   the syntax has been extracted, and is shown below in its expanded
   state. The following is an example of how this looks:
\begin{quote}
   {\tt SAY} {\it someting} {\tt TO} {\it someone}
\begin{quote}\tt
\begin{tabbing}
   {\it something} : \= HI\\
                     \> HELLO\\
                     \> BYE
\end{tabbing}
\begin{tabbing}
   {\it someone} : \= THE BOSS\\
		   \> YOUR NEIGHBOR
\end{tabbing}
\end{quote}
\end{quote}
   You can generally identify these situations by the fact that they
   comes a bit below the real syntax diagram, and that they contains a
   colon character after the name of the term to be expanded. 
\end{itemize}

In the syntax diagrams, some generic names have been used for the
various parts, in order to indicate common attributes for the term.
For instance, whenever a term in the syntax diagrams is called {\it
expr}, it means that any valid {\rexx} expression may occur instead of
that term. The most common such names are:
\begin{description}
\item[\it condition]
   indicates that the subclause can be any of the names of the
   conditions, e.g.\ {\tt SYNTAX}, {\tt NOVALUE}, {\tt HALT}, etc. 

\item[\it expr]
   indicates that the subclause can be any valid {\rexx} expression,
   and will in general be evaluated as normal during execution.

\item[\it statement]
   indicates that extra clauses may be inserted into the instruction,
   and that exactly one of them must be a true statement. 

\item[\it string]
   indicates that the subclause is a constant string, i.e.\ either
   enclosed by single quotes (\verb|'|...\verb|'|) or double quotes
   (\verb|"|...\verb|"|).


\item[\it symbol]
   indicates that the subclause is a single symbol. In general,
   whenever {\it symbol} is used as the name for a subclause, it means
   that the symbol will not automatically be expanded to the value of
   the symbol. But instead, some operation is performed on the name of
   the symbol. 
   
\item[\it template]
   indicates that the subclause is a parsing template. The exact
   syntax of this is explain in a chapter on tracing, to be written
   later.
\end{description}
In addition to this, variants may also exists. These variants will
have an extra letter or number appended to the name of the subclause,
and is used for differing between two or more subclauses having the
same ``type'' in one syntax diagram. In the case of other names for
the subclauses, these are explained in the description of the
instruction. 



\subsection{The {\tt ADDRESS} Instruction}
\begin{syntax}
\begin{tabbing}
   ADDRESS \= $[$ {\it environment} $[$ {\it command} $]$ $]$ ;\\
           \> $[$ $[$ VALUE $]$ {\it expression} $]$ ;
\end{tabbing}
\end{syntax}
\label{inst:address}
\index{ADDRESS@{\ptt ADDRESS}|(bold}
\index{VALUE@{\ptt VALUE}|(bold}
\index{environment|(bold}
\index{command|(bold}

The {\tt ADDRESS} instruction controls where commands to external
environment are sent.  If both {\it environment} and {\it 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\refer{sec:commands}, except that the environment
in which it is to be executed can be explicitly specified in the {\tt
ADDRESS} clause. In this case, the special variable {\tt
RC}\index{special variable!{\tt RC}} will be set as usual, and the
{\tt ERROR}\index{condition!ERROR@{\tt ERROR}} or {\tt
FAILURE}\index{condition!FAILURE@{\tt FAILURE}} conditions might be
raised, as for normal commands.

The {\it 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 {\it command\/} and {\it expression}
terms can be any {\rexx} expression.

{\rexx} maintains a list of environments\index{environment!list of},
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 {\it
command\/} is specified, the contents of the environment stack is not
changed. If you omit {\it command}, {\it environment} will always be
put in the front of the list of
environments.\index{environment!selecting}

What happends 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 {\tt ADDRESS},
the effect is to swap the two first entries in the list of
environments. Consequently, executing {\tt ADDRESS} multiple times
will toggle between two environments.

The second syntax form of {\tt ADDRESS} is a special case of the first
form with {\it command\/} omitted. If the first token after {\tt
ADDRESS} is {\tt 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 {\tt 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 {\tt VALUE} and {\it
command\/} in a single clause.

\begin{example}[Examples of the {\tt ADDRESS} instruction]
You can omit the {\tt VALUE} keyword if the
expression following {\tt ADDRESS} starts with a token which is
neither a symbol or a literal string.  Confused? Let's look at some
examples:
\begin{quote}
   {\tt ADDRESS COMMAND}\\
   {\tt ADDRESS SYSTEM 'copy' fromfile tofile}\\
   {\tt ADDRESS system}\\
   {\tt ADDRESS VALUE newenv}\\
   {\tt ADDRESS}\\
   {\tt ADDRESS (oldenv)}
\end{quote}
The first of these sets the environment {\tt COMMAND} as the current
environment\index{environment!current}. The second performs the
command {\tt copy} in the environment {\tt SYSTEM}, using the values
of the symbols\/ {\tt fromfile} and {\tt tofile} as parameters.  Note
that this will not set {\tt SYSTEM} as current environment. The third
example sets {\tt 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 {\tt newenv}, pushing
{\tt SYSTEM} down one level in the stack. The fifth clause swap the
two uppermost entries on the stack; and {\tt SYSTEM} ends up at the
top.  The last example sets the current environment to whatever is the
value of the symbol {\tt oldenv}.
\end{example}

\begin{example}[The {\tt VALUE} subkeyword]
Let us look a bit closer at the last example. Note the differences
between the two clauses:
\begin{quote}
   {\tt ADDRESS OLDENV}\\
   {\tt ADDRESS (OLDENV)}
\end{quote}
The first of these sets the current default environment to {\tt
OLDENV}, while the second sets it to the value of the symbol\/ {\tt
OLDENV}. Actually, in the latter, the subkeyword {\tt VALUE} has been
omitted, which is legal since the parameter starts with a special
character.
\end{example}

If you are still confused, Don't Panic; the syntax of {\tt 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\index{environment!names}?
Well, that is implementation-specific, but some names seems to be in
common use. The name {\tt 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 ({\tt CMS},
{\tt UNIX}, etc).  You have to consult the implementation specific
documentation for more information about this. Actually, there is not
really any restrictions on what constitues 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\index{interpreter!invokation}, although TRL
defines that one environment is automatically preselected when
starting up a {\rexx} script. Note that there does not exist any {\tt
NONE} environment in standard {\rexx}, i.e.~an environment that
ignores commands. But some interpreters implement the {\tt TRACE}
setting ??? which acomplish this.

The list of environments will be saved across subroutine
calls\index{subroutine!saved settings}; so the effect of any {\tt
ADDRESS} clauses in the subroutine will cease upon return from the
subroutine.
\index{ADDRESS@{\ptt ADDRESS}|)}
\index{VALUE@{\ptt VALUE}|)}
\index{environment|)}
\index{command|)}


\subsection{The {\tt ARG} Instruction}
\begin{syntax}
   ARG $[$ {\it template} $]$ ;
\end{syntax}
\index{ARG@{\ptt ARG}|(bold}

The {\tt ARG} instruction will parse the argument strings\index{argument}
at the current procedureal level into the template. Parsing will be
performed in upper case mode. This clause is equivalent to:
\begin{quote}   
   {\tt PARSE UPPER ARG $[$ {\it template} $]$ ;}
\end{quote}
For more information, see the \ttidx{PARSE}\refer{inst:parse} 
instruction. Note that this is the only situation where a multistring
template is relevant.

\begin{example}[Beware assignments]
The similarity between {\tt ARG} and {\tt PARSE UPPER ARG} has one
exception. Suppose the {\tt PARSE UPPER ARG} has an absolute positional
pattern as the first element in the template, like:
\begin{quote}\tt
parse upper arg =(foo) bar
\end{quote}
This is not equivalent to an {\tt ARG} instruction, because {\tt ARG}
instruction would become an assignment. A simple trick to avoid this
problem is just to prepend a placeholder period ({\tt .}\@) to the
pattern, thus the equal sign (\/{\tt =}) is no longer the second token
in the new {\tt ARG} instruction. Also, unless the absolute positional
pattern is indirect, the equal sign can be removed without changing
the meaning of the statement.
\end{example}



\index{ARG@{\ptt ARG}|)}


\subsection{The {\tt CALL} Instruction}
\begin{syntax}
\begin{tabbing}
   CALL \= {\it routine} $[$ {\it parameter} $]$ 
                             $[$, $[$ {\it parameter} $]$ ... $]$ ;\\
        \> $\{$ ON $|$ OFF $\}$ {\it condition} $[$ NAME {\it label} $]$ ;
\end{tabbing}
\end{syntax}

\index{CALL@{\ptt CALL}|(bold}
The {\tt CALL} instruction invokes a
subroutine\index{subroutine|bold}, named by {\it routine}, which can
be internal\index{subroutine!internal},
built-in\index{subroutine!built-in}, or
external\index{subroutine!external}; and the three reposititories of
functions are searched in that order. are searched for {\it routine}
in that order. The token {\it routine} must be either a literal string
or a symbol (which is taken literally).  However, if {\it
routine} is a literal string, the pool of internal
subroutines\index{subroutine!internal} is not searched. Note that some
interpreters may have additional repositories of labels to search.

In a {\tt CALL} instruction, each {\it parameter} is evaluated,
strictly in order from left to right, and passed as an
argument\index{argument} to the subroutine.  A {\it parameter} might
be left out (i.e.~an empty argument\index{argument!empty}), which is
not the same as passing the nullstring as argument.

\begin{example}
Users often confuse a parameter which is the nullstring with leaving
out the parameter. However, this is two very different situations.
Consider the following calls to the built-in function {\tt
TRANSLATE()}:
\begin{quote}\tt
   say translate('abcDEF'   )   /* says ABCDEF */\\
   say translate('abcDEF',"")   /* says abcDEF */\\
   say translate('abcDEF',,"")  /* says '~~~~~~' */
\end{quote}
The {\tt TRANSLATE()} function is able to differ between receiving the
nullstring (i.e.\ a defined string having zero length), from the
situation where a parameter was not specified (i.e.\ the undefined
string). Since {\tt TRANSLATE()} is one of the few functions where the
parameters' default values are very different from the nullstring,
the distinction becomes very visible. 
\end{example}


For the {\tt CALL} instruction, watch out for interference with line
continuation\index{line continuation}. If there are trailing commas, it
might be interpreted as line continuation. If a {\tt CALL} instruction
use line continuation between two parameters, two commas are needed:
one to separate the parameters, and one to denote line continuation.

A number of settings are stored across internal subroutine
calls\index{subroutine!saved settings}. An internal subroutine will
inherit the values in effect when the call is made, and the settings
are restored on exit from the subroutine.  These settings are:
\begin{itemize}
\item
   Conditions traps\index{condition trap}, see chapter
   {\ref{ch:conditions}}. 

\item
   Current trapped condition\index{current trapped condition}, see
   section {\ref{sect:CTS}}.

\item
   \ttidx{NUMERIC} settings, see section {\ref{inst:numeric}}. 

\item
   \ttidx{ADDRESS} environments\index{environment}, see section
   {\ref{inst:address}}. 

\item
   \ttidx{TRACE} mode, see section{\ref{inst:trace}} and chapter
   [not yet written]. 

\item
   The elapse time clock\index{time!elapse clock}, see section
   {\ref{bif:time}}. 
\end{itemize}
Also, the {\ttidx{OPTIONS}} settings may or may not be restored,
depending on the implementation.  Further, a number of other things
may be saved across internal subroutines. The effect on variables are
controlled by the {\ttidx{PROCEDURE}} instruction in the subroutine
itself. The state of all {\tt DO}-loops\index{loop} will be preserved
during subroutine calls.

\begin{example}[Subroutines and trace settings]
Subroutines can not be used to set various settings like trace
settings, {\tt NUMERIC} settings, etc. Thus, the following code will
not work as intended:
\begin{quote}
\begin{tabbing}
XXX\=\kill
   say digits() /* says 9, maybe */\\
   call inc\_digits\\
   say digits() /* still says 9 */\\
   exit\\
~\\
   inc\_digits:\\
      numeric digits digits() + 1\
      return
\end{tabbing}
\end{quote}
The programmer probably wanted to call a routine which incremented the
precision of arithmetic operations. However, since the setting of {\tt
NUMERIC DIGITS} is saved across subroutine calls, the new value set in
{\tt inc\_digits} is lost at return from that routine. Thus, in order
to work correctly, the {\tt NUMERIC} instruction must be located in
the main routine itself.
\end{example}

Built-in subroutines will have no effect on the settings, except for
explicitly defined side effects. Nor will external subroutines change
the settings. For all practical purposes, an external subroutine is
conceptually equivalent to reinvoking the interpreter in a totally
separated process.

If the name of the subroutine is specified by a literal string, then
the name will be used as-is; it will not be converted to upper case.
This is important because a routine which contains lower case lettes
can only be invoked by using a literal string as the routine name in
the {\tt CALL} instruction.

\begin{example}[Labels are literals]
Labels are literal, which means that they are neither tail-substituted
nor substituted for the value of the variable. Further, this also
means that the setting of {\tt NUMERIC DIGITS} has no influence on the
section of labels, even when the labels are numeric symbols. Consider
the following code:
\begin{quote}\tt
\begin{tabbing}
XXX\=\kill
   call 654.32\\
   exit\\
\>\\
   654.321: \\
\>    say here\\
\>    return \\
\\
   654.32: \\
\>    say there\\
\>    return
\end{tabbing}
\end{quote}
In this example, the second of the two subroutines are always chosen,
independant of the setting of {\tt NUMERIC DIGITS}. Assuming that {\tt
NUMERIC DIGITS} are set to 5, then the number 654.321 is converted to
654.32, but that does not affect labels. Nor would a statement {\tt
CALL 6.5432E2} call the second label, even though the numberic value
of that symbol is equal to that of one of the labels. 
\end{example}

The called subroutines may or may not return data to the
caller\index{return value}. In the calling routine, the special
variable\index{variable!special} \ttidx{RESULT} will be set to the
return value or dropped, depending on whether any data was returned
or not. Thus, the {\tt CALL} instruction is equivalent to calling the
routine as a function, and assigning the return value to {\tt RESULT},
except when the {\it routine} does not return data.

In {\rexx}, recursive\index{recursion} routines are allowed. A minimum
number of 100 nested internal and external subroutine invocations, and
support for a minimum of 10 parameters\index{argument} for each call
are required by {\rexx}. See chapter {\ref{ch:limits}} for more
informtion concerning implementation limits.\index{CALL@{\ptt CALL}|)}

When the token following {\tt CALL} is either {\tt ON} or {\tt OFF},
the {\tt CALL} instruction is not used for calling a subroutine, but
for setting up condition traps. In this case, the third token of the
clause must be the name of a condition, which setup is to be changed.
If the second token was {\tt ON}, then there can be either three or
five tokens. If the five token version is used, then the fourth token
must be {\tt NAME} and the fifth token is taken to be the symbolic
name of a label, which is the condition handler. This name can be
either a constant string, or a symbol, which is taken literally.  When
{\tt OFF} is used, the named condition trap is turned off.

Note that the {\tt ON} and {\tt OFF} forms of the {\tt CALL}
instruction were introduced in TRL2. Thus, they are not likely
to be present on older interpreters. More information about conditions
and condition traps are given in a chapter \refer{ch:conditions}.


\subsection{The {\tt DO}/{\tt END} Instruction}
\begin{syntax}
   DO $[$ {\it repetitor} $]$ $[$ {\it conditional} $]$ ;   
                                  $[$ {\it clauses} $]$
                                       END $[$ {\it symbol} $]$ ;
\begin{quote}\tt
\begin{tabbing}
   {\it repetitor} : \= {\it symbol} = {\it expri} $[$ TO {\it exprt} $]$
                              $[$ BY {\it exprb} $]$ $[$ FOR {\it exprf} $]$\\
                     \> {\it exprr}\\
                     \> FOREVER
\end{tabbing}
\begin{tabbing}
   {\it conditional} : \= WHILE {\it exprw}\\
                       \> UNTIL {\it expru}
\end{tabbing}
\end{quote}
\end{syntax}

\index{DO@{\ptt DO}|(bold}
\index{END@{\ptt END}|(bold}
\index{FOREVER@{\ptt FOREVER}}
\index{TO@{\ptt TO}}
\index{BY@{\ptt BY}}
\index{FOR@{\ptt FOR}}
\index{FOREVER@{\ptt FOREVER}}
\index{WHILE@{\ptt WHILE}}
\index{UNTIL@{\ptt UNTIL}}
\index{conditional}
\index{repetitor}
The {\tt DO}/{\tt END} instruction is the instruction used for
looping\index{loop} and grouping several statements into one block.
This is a multi-clause instruction.

The most simple case is when there is no {\it repetitor} or {\it
conditional}, in which case it works like {\tt BEGIN}/{\tt END} in
Pascal\index{Pascal} or {\tt \{}...{\tt \}} in C\index{C}. I.e.\ it
groups zero or more {\rexx} clauses into one conceptual statement. 

The {\it repetitor} subclause controls the control
variable\index{variable!control} of the loop, or the number of
repetitions. The {\it exprr} subclause may specify a certain number of
repetitions, or you may use {\tt FOREVER} to go on looping forever.

If you specify the control variable {\it symbol}, it must be a
variable symbol, and it will get the initial value {\it expri} at the
start of the loop. At the start of each iteration, including the
first, it will be checked whether it has reached the value specified by
{\it exprt}. At the end of each iteration the value {\it exprb} is
added to the control variable. The loop will terminate after at most
{\it exprf} iterations. Note that all these expressions are evaluated
only once, before the loop is entered for the first iteration.

You may also specify {\tt UNTIL} or {\tt WHILE}, which take a boolean
expression\index{boolean expression}. {\tt WHILE} is checked before
each iteration, immediately after the maximum number of iteration has
been performed. {\tt UNTIL} is checked after each iteration,
immediately before the control variable is incremented. It is not
possible to specify both {\tt UNTIL} and {\tt WHILE} in the same {\tt
DO} instruction.

The {\tt FOREVER} keyword is only needed when there is no {\it
conditional}, and the {\it repetitor} would also be empty if {\tt
FOREVER} was not specified. Actually, you could rewrite this as {\tt
DO WHILE 1}. The two forms are equivalent, except for tracing output. 

The subclauses {\tt TO}, {\tt BY}, and {\tt FOR} may come in any
order, and their expressions are evaluated in the order in which they
occur. However, the initial assignment must always come first. Their
order may affect your program if these expressions have any side
effects.  However, this is seldom a problem, since it is quite
intuitive. Note that the counting of iterations, if the {\tt FOR}
subclause has been specified, is never affected by the setting of {\tt
NUMERIC DIGITS}. 

\begin{example}[Evaluation order]
What may prove a real trap, is that although the value to which the
control variable is set is evaluated before any other expressions in
the {\it repetitor}, it is assigned to the control variable after all
expressions in the {\it repetitor} have been evaluated.

The following code illustrates this problem:
\begin{quote}\tt
\begin{tabbing}
   XXX\=\kill
   ctrl = 1\\
   do ctrl=f(2) by f(3) to f(5)\\
   \> call func(6)\\
   \> end\\
   call func(7)\\
   exit\\
   ~\\
   f:\\
   \> say 'ctrl='ctrl 'arg='arg(1)\\
   \> return arg(1)
\end{tabbing}
\end{quote}
This code produces the following output:
\begin{quote}\tt
   ctrl=1 arg=2\\
   ctrl=1 arg=3\\
   ctrl=1 arg=5\\
   ctrl=2 arg=6\\
   ctrl=5 arg=6\\
   ctrl=8 arg=7
\end{quote}
Make sure you understand why the program produces this output.
Failure to understand this may give you a surprise later, when you
happen to write a complex {\tt DO}-instruction, and do not get the
expected result. 
\end{example}

If the {\tt TO} expression is ommitted, there is no checking for an
upper bound of the expression. If the {\tt BY} subclause is ommitted,
then the default increment of 1 is used. If the {\tt FOR} subclause is
omitted, then there is no checking for a maximum number of iterations.

\begin{example}[Loop convergence]
For the reasons just explained, the instruction:
\begin{quote}\tt
\begin{tabbing}
XXX\=\kill
	do ctrl=1\\
\>	   nop\qquad /* and other statements */\\
\>	   end
\end{tabbing}
\end{quote}
will start with {\tt CTRL} being 1, and then iterate through 2, 3, 4,
..., and never terminate except by {\tt LEAVE}, {\tt RETURN}, {\tt
SIGNAL}, or {\tt EXIT}. 

Although similar constructs in other languages typically provokes an
overflow at some point, something ``strange'' happens in {\rexx}.
Whenever the value of\/ {\tt ctrl} becomes too large, the
incrementation of that variable produces a result that is identical to
the old value of {\tt ctrl}. For {\tt NUMERIC DIGITS} set to 9, this
happens when {\tt ctrl} becomes 1.00000000E+9. When adding 1 to this
number, the result is still 1.00000000E+9. Thus, the loop
``converges'' at that value.

If the value of {\tt NUMERIC DIGITS} is 1, then it will ``converge''
at 10, or 1E+1 which is the ``correct'' way of writing that number
under {\tt NUMERIC DIGITS 1}.  You can in general disregard loop
``convergence'', because it will only occur in very rare situations.
\end{example}

\begin{example}[Difference between {\tt UNTIL} and {\tt WHILE}]
One frequent misunderstanding is that the {\tt WHILE} and {\tt UNTIL}
subclauses of the {\tt DO}/{\tt END} instruction are equivalent,
except that {\tt WHILE} is checked before the first iteration, while
{\tt UNTIL} is first checked before the second iteration. 

This may be so in other languages, but in {\rexx}. Because of the
order in which the parts of the loop are performed, there are other
differences. Consider the following code:
\begin{quote}\tt
\begin{tabbing}
XXX\=\kill
   count = 1\\
   do i=1 while count\verb|\|=5\\
\>    count count + 1\\
\>    end\\
   say i count\\
~\\
   count = 1\\
   do i=1 until count=5\\
\>    count count + 1\\
\>    end\\
   say i count
\end{tabbing}
\end{quote}
After the first loop, the numbers 6 and 5, while in the second loop,
the numbers 5 and 5 are written out. The reason is that a {\tt WHILE}
clause is checked after the control variable of the loop has been
incremented, but an {\tt UNTIL} expression is checked before the
incrementation. 
\end{example}

A loop can be terminated in several ways. A {\tt RETURN} or {\tt EXIT}
instruction terminates all active loops in the procedure levels
terminated. Further, a {\tt SIGNAL} instruction transferring control
(i.e.\ neither a {\tt SIGNAL ON} nor {\tt SIGNAL OFF}) terminates all
loops at the current procedural level. This applies even to
``implict'' {\tt SIGNAL} instructions, i.e.\ when triggering a
condition handler by the method of {\tt SIGNAL}. A {\tt LEAVE}
instruction terminates one or more loops. Last but not least, a loop
can terminate itself, when it has reached its specified stop
conditions.

Note that the {\tt SIGNAL} instruction terminates also non-repetitive
loops (or rather: {\tt DO}/{\tt END} pairs), thus after an {\tt
SIGNAL} instruction, you must not execute an {\tt END} instruction
without having executed its corresponding {\tt DO} first (and after
the {\tt SIGNAL} instruction). However, as long as you stay away from
the {\tt END}s, it is all right according to TRL to execute code
within a loop without having properly activated the loop itself.

Note that on exit from a loop, the value of the control variable has
been incremented once after the last iteration of the loop, if the
loop was terminated by the {\tt WHILE} expression, by exceeding the
number of max iterations, or if the control variable exceeded the stop
value. However, the control variable has the value of the last
iteration if the loop was terminated by the {\tt UNTIL} expression, or
by an instruction inside the loop (e.g.\ {\tt LEAVE}, {\tt SIGNAL},
etc). 

The following algoritm in {\rexx} code shows the execution of a {\tt
DO} instruction, assuming that {\it expri}, {\it exprt}, {\it exprb},
{\it exprf}, {\it exprw}, {\it expru}, and {\it symbol} have been taken
from the syntax diagram of {\tt DO}.
\begin{quote}\tt
\begin{tabbing}
	XXX\=XXX\=\kill
	@expri = {\it expri}\\
	@exprt = {\it exprt}\\
	@exprb = {\it exprb}\\
	@exprf = {\it exprf}\\
	@iters = 0 \\
	{\it symbol} = @expri\\
	start\_of\_loop:\\
\>	   if {\it symbol} > @extrt then signal after\_loop\\
\>	   if @iters > @exprf then signal after\_loop \\
\>	   if \verb|\| {\it exprw} then signal after\_loop\\
\>\>	      {\it instructions}\\
\>	   end\_of\_loop:\\
\>	   if {\it expru} then signal after\_loop\\
\>	   {\it symbol} = {\it symbol} + @exprb\\
\>	   signal start\_of\_loop\\
	after\_loop:
\end{tabbing}
\end{quote}
Some notes are in order for this algoritm. First, it uses the {\tt
SIGNAL} instruction, which is defined to terminate all active loops.
This aspect of the {\tt SIGNAL} instruction has been ignored for the
purpose of illustrating the {\tt DO}, and consequently, the code shown
above is not suitable for nested loops. Further, the order of the
first four statements should be identical to the order in the
corresponding subclauses in the {\it repetitor}. The code has also
ignored that the {\tt WHILE} and the {\tt UNTIL} subclauses can not be
used in the same {\tt DO} instruction. And in addition, all variables
starting with the at sign ({\tt @}), are assumed to be internal
variables, private to this particular loop. Within {\it instructions},
a {\tt LEAVE} instruction is equivalent to {\tt signal after\_loop},
while a {\tt ITERATE} instruction is equivalent to {\tt signal
end\_of\_loop}.
\index{DO@{\ptt DO}|)}
\index{END@{\ptt END}|)}



\subsection{The {\tt DROP} Instruction}
\begin{syntax}
   DROP {\it symbol} $[$ {\it symbol} ... $]$ ;
\end{syntax}
\index{DROP@{\ptt DROP}|(bold}
\index{variable|(bold}
\index{default value|see{\rm value, initial}}

The {\tt DROP} instruction makes the named {\it variable\/}s
uninitialized, i.e.~the same state that they had at the startup of the
program\index{value!initial}. The list of variable names are processed
strictly from left to right and dropped in that order.  Consequently,
if one of the variables to be dropped is used in a
tail\index{variable!tail} of another, then the order might be
significant. E.g.~the following two {\tt DROP} instructions are not
equivalent:
\begin{quote}
\begin{verbatim}
bar = 'a'
drop bar foo.bar  /* drops 'BAR' and 'FOO.BAR' */
bar = 'a'
drop foo.bar bar  /* drops 'FOO.a' and 'BAR'
\end{verbatim}
\end{quote}

The {\it variable} terms can be either a variable symbol or a symbol
enclosed in parentheses. The former form is first tail-substituted,
and then taken as the literal name of the symbol to be dropped. The
result names the variable to drop. In the latter form, the value of
the variable symbol inside the parentheses is retrieved and taken as a
space separated list of symbols. Each of these symbols is
tail-substituted (if relevant); and the result is taken as the literal
name of a variable to be dropped. However, this process is not
recursive, so that the list of names refered to indirectly can not
itself contain parantheses. Note that the second form was
introduced in TRL2, mainly in order to make
{\ttidx{INTERPRET}} unnecessary.\index{variable!indirectly named} 

In general, things contained in parantheses can be any valid {\rexx}
expression, but this does not apply to the {\tt DROP}, {\tt PARSE},
and {\tt PROCEDURE} instructions. 

\begin{example}[Dropping compound variables]
Note a potential problem for compound
variables\index{variable!compound}: when a stem
variable\index{variable!stem} is set, it will not set a default value,
rather it will assign ``all possible variables'' in that stem
collection\index{stem collection} at once. So dropping a compound
variable in a stem collection for which the stem variable has been
set, will set that compound variable to the original uninitialized
value;\index{value!initial} not the value of the stem variable. See
section \ref{sect:assign} for further notes on assignments.  To
illustrate consider the code:
\begin{quote}\tt
   foo.~= 'default'\\
   drop baz bar foo.bar\\
   say foo.bar foo.baz /* says 'FOO.BAR default' */
\end{quote}
In this example, the {\tt SAY} instruction writes out the value of the
two compound variables {\tt FOO.BAR} and {\tt FOO.BAZ}. When
performing tail-substitution for these, the interpreter finds that
both {\tt BAR} and {\tt BAZ} are unitialized. Further, {\tt FOO.BAR}
has also been made uninitialized, while {\tt FOO.BAZ} has the value
assigned to it in the assignment to the stem variable. 
\end{example}

\begin{example}[Tail-substitution in {\tt DROP}]
For instance, suppose that the variable {\tt FOO} has the value {\tt
bar}. After being dropped, {\tt FOO} will have its uninitialized
value, which is the same as its name: {\tt FOO}. If the variable to be
dropped is a stem variable, then both the stem variable and all
compound variables of that stem become uninitialized.
\begin{quote}\tt
   bar = 123\\
   drop foo.bar ~ /* drops 'FOO.123' */
\end{quote}
\end{example}

Technically, it should be noted that some operations involving
dropping of compound variables\index{variable!compound} can be very
space consuming. Even though the standard does not operate with the
term ``default value'' for the value assigned to a stem
variable\index{variable!stem}\index{value!initial}, that is the way in
which it is most likely to be implemented. When a stem is assigned a
value, and some of its compound variables are dropped afterwards, then
the interpreter must use memory to store references to the variables
dropped. This might seem counterintuitive at first, since dropping
ought to release memory, not allocate more\index{memory
considerations}.

There is a parallel between {\tt DROP} and {\tt PROCEDURE EXPOSE}. 
However, there is one important difference, although {\tt PROCEDURE
EXPOSE} will expose the name of a variable enclosed in parantheses
before starting to expose the symbols that variable refers to, this is
not so for {\tt DROP}. If {\tt DROP} had mimiced the behavior of {\tt
PROCEDURE EXPOSE} in this matter, then the whole purpose of indirect
specifying of variables in {\tt DROP} would have been defeated.

Dropping a variable which does not have a value is not an error.
There is no upper limit on the number of variables that can be dropped
in one {\tt DROP} clause, other than restrictions on the clause
length.  If an exposed variable\index{variable!exposed} is dropped,
the variable in the caller is dropped, but the variable remains
exposed. If it reassigned a value, the value is assigned to a
variable in the caller routine.
\index{DROP@{\ptt DROP}|)}
\index{variable|)}


\subsection{The {\tt EXIT} Instruction}
\begin{syntax}
   EXIT $[$ {\it expr} $]$ ;
\end{syntax}
\index{EXIT@{\ptt EXIT}|(bold}
\index{value!return|see{\rm return value}}

Terminates the {\rexx} program\index{return value}, and optionally
returns the expression {\it expr} to the caller. If specified, {\it
expr} can be any string.  In some systems, there are restrictions
on the range of valid values for the {\it expr}. Often the return
expression must be an integer, or even a non-negative integer.
This is not really a restriction on the {\rexx} language itself, but a
restriction in the environment\index{environment} in which the
interpreter operates, check the system dependent documentation for
more information.

If {\it expr} is omitted, nothing will be returned to the caller.
Under some circumstances that is not legal, and might be handled as an
error or a default value might be used. The {\tt EXIT} instruction
behaves differently in a ``program'' than in an external
subroutine\index{subroutine!external}. In a ``program'', it returns
control to the caller e.g.~the operating system command interpreter.
While for an external routine, it returns control to the calling
{\rexx} script, independent of the level of nesting inside the
external routine being terminated.

\begin{table}[htb]
\begin{flushleft}
\begin{tabular}{|p{2in}|p{1.5in}|p{1.5in}|} \hline
 & \hfil {\tt RETURN} & \hfil {\tt EXIT}\\\hline
{\raggedright At the main level of the program} &
	{\raggedright Exits program} & 
		{\raggedright Exits program}\\\hline
%
{\raggedright At an internal subroutine level of the program} &
	\parbox[t]{1.5in}{\raggedright 
           Exits subroutine, and returns to caller} &
		{\raggedright Exits program}\\\hline
%
{\raggedright At the main level of an external subroutine} &
	\parbox[t]{1.5in}{\raggedright Exits the external subroutine}&
	\parbox[t]{1.5in}{\raggedright Exits the external subroutine}\\\hline
%
{\raggedright At a subroutine level within an external subroutine} &
	\parbox[t]{1.5in}{\raggedright 
        Exits the subroutine, returning to calling 
        routine within external subroutine script} &
	\parbox[t]{1.5in}{\raggedright Exits the external subroutine}\\\hline
\end{tabular}
\end{flushleft}
\caption{Actions of {\tt RETURN} and {\tt EXIT} Instructions}
\label{tab:rexit}
\end{table}

If terminating an external routine (i.e.~returning to the calling
{\rexx} script) any legal {\rexx} string value is allowed as a return
value. Also, no return value can be returned, and in both cases, this
information is successfully transmitted back to the calling
routine.  In the case of a function call (as opposed to a
subroutine call), returning no value will raise {\tt SYNTAX} condition
{\syntaxerror{44}}. Table \ref{tab:rexit} describes the actions taken
by the {\tt EXIT} and {\tt RETURN} instruction in various situations. 
\index{EXIT@{\ptt EXIT}|)}



\subsection{The {\tt IF}/{\tt THEN}/{\tt ELSE} Instruction}
\begin{syntax}
   IF {\it expr} $[$;$]$ THEN $[$;$]$ {\it statement} 
                          $[$ ELSE $[$;$]$ {\it statement} $]$ 
\end{syntax}
\index{IF@{\ptt IF}|(bold}
\index{THEN@{\ptt THEN}|(bold}
\index{ELSE@{\ptt ELSE}|(bold}

This is a normal if-construct. First the boolean
expression\index{boolean expression} {\it expr} is evaluated, and its
value must be either {\tt 0} or {\tt 1} (everything else is a syntax
error which raises {\tt SYNTAX} condition number {\syntaxerror{34}}).
Then, the statement following either {\tt THEN} or {\tt ELSE} is
executed, depending on whether {\it expr} was {\tt 1} or {\tt 0},
respectively.

Note that there must come a statement after {\tt THEN} and {\tt ELSE}.
It is not allowed to put just a null-clause\index{null clause} (i.e.\
a comment or a label) there.  If you want the {\tt THEN} or {\tt ELSE}
part to be empty, use the {\ttidx{NOP}} instruction. Also note that
you can not directly put more than one statement after {\tt THEN} or
{\tt ELSE}; you have to package them in a \ttidx{DO}-\ttidx{END} pair
to make them a single, conceptual statement.

After {\tt THEN}, after {\tt ELSE}, and before {\tt THEN}, you might
put one or more clause delimitors (newlines or semicolons), but these
are not required. Also, the {\tt ELSE} part is not required either, in
which case no code is executed if {\it expr} is false (evaluates to
{\tt 0}). Note that there must also be a statement separator before
{\tt ELSE}, since the that statement must be terminated. This also
applies to the statement after {\tt ELSE}.  However, since {\it
statement} includes a trailing clause delimitor itself, this is not
explicitly shown in the syntax diagram.

\begin{example}[Dangling {\tt ELSE}]
Note the case of the ``dangling'' {\tt ELSE}\index{dangling {\tt
ELSE}}.  If an {\tt ELSE} part can correctly be thought of as
belonging to more than one {\tt IF}/{\tt THEN} instruction pair, it
will be parsed as belonging to the closest (i.e.~innermost) {\tt IF}
instruction:
\begin{quote}
\begin{verbatim}
parse pull foo bar
if foo then 
   if bar then
      say 'foo and bar are true'
   else
      say 'one or both are false'
\end{verbatim}
\end{quote}
In this code, the {\tt ELSE} instruction is nested to the innermost
{\tt IF}, i.e.\ to {\tt IF BAR THEN}. 
\end{example}
\index{IF@{\ptt IF}|)}
\index{THEN@{\ptt THEN}|)}
\index{ELSE@{\ptt ELSE}|)}


\subsection{The {\tt INTERPRET} Instruction}
\begin{syntax}
   INTERPRET {\it expr} ;
\end{syntax}
\index{INTERPRET@{\ptt INTERPRET}|(bold}

The {\tt INTERPRET} instruction is used to dynamically build and
execute {\rexx} instructions during run-time. First, it evaluates the
expression {\it expr}, and then parses and interprets the result as a
(possibly empty) list of {\rexx} instructions to be executed. For
instance:
\begin{quote}
   {\tt foo = 'hello, world'}\\
   {\tt interpret 'say "'foo'!"'}
\end{quote}
executes the statement {\tt SAY "hello, world!"} after having
evaluated the expression following {\tt INTERPRET}. This example shows
several important aspects of {\tt INTERPRET}. Firstly, it's very easy
to get confused by the levels of quotes, and a bit of caution should be
taken to nest the quotes correctly. Secondly, the use of {\tt
INTERPRET} does not exactly improve readability.

Also, {\tt INTERPRET} will probably increase execution
time\index{execution time} considerably if put inside
loops\index{loop}, since the interpreter may be forced to reparse the
source code for each iteration. Many optimizing\index{optimalization}
{\rexx} interpreters\index{interpreter} (and in particular {\rexx}
compilers\index{compiler}) has little or no support for {\tt
INTERPRET}. Since virtually anything can happen inside it, it is hard
to optimize, and it often invalidates assumptions in other parts of
the script, forcing it to ignore other possible optimalizations. Thus,
you should avoid {\tt INTERPRET} when speed is at a premium.

There are some restrictions on which statements can be inside an {\tt
INTERPRET} statement. Firstly, labels cannot occur there. TRL
states that they are not allowed, but you may find that in some 
implementations labels occurring there will not affect the
label\index{label} symbol table of the program being run. Consider the
statement: 
\begin{quote}
   {\tt interpret 'signal there; there: say hallo'}\\
   there:
\end{quote}
This statement transfers control to the label {\tt THERE} in the
program, never to the {\tt THERE} label inside the expression of
the {\tt INTERPRET} instruction. Equivalently, any \ttidx{SIGNAL}
to a label {\tt THERE} elsewhere in the program never transfers
control to the label inside the {\tt INTERPRET} instruction. However,
labels are strictly speaking not allowed inside {\tt INTERPRET}
strings.

\begin{example}
There is an idea for a selfmodifying program in {\rexx} which is
basically like this:
\begin{quote}
\begin{verbatim}
string = ''
do i=1 to sourceline()
   string = string ';' sourceline(i)
   end

string = transform( string )
interpret string
exit

transform: procedure 
   parse arg string
   /* do some tranformation on the argument */
   return string
\end{verbatim}
\end{quote}
Unfortunately, there are several reasons why this program will not
work in {\rexx}, and it may be instructive to investigate why.
Firstly, it uses the label {\tt TRANSFORM}, which is not allowed in
the argument to {\tt INTERPRET}. The interpret will thus refer to the
{\tt TRANSFORM} routine of the ``outermost'' invocation, not the one
``in'' the {\tt INTERPRET} string.

Secondly, the program does not take line continuations into mind.
Worse, the {\tt SOURCELINE()} built-in function refers to the data
of the main program, even inside the code executed by the {\tt
INTERPRET} instruction.  Thirdly, the program will never end, as it
will nest itself up till an implementation-dependant limit for the
maximum number of nested {\tt INTERPRET} instructions.

In order to make this idea work better, temporary files should
be used. 
\end{example}
%
On the other hand, loops\index{loop} and other multi-clause instructions, like
\ttidx{IF} and \ttidx{SELECT} occur inside an {\tt
INTERPRET} expression, but only if the whole instruction is there; you
can not start a structured instruction inside an {\tt INTERPRET}
instruction and end it outside, or vice-versa. However, the
instruction {\tt SIGNAL} is allowed even if the label is not in the
interpreted string. Also, the instructions {\tt ITERATE} and {\tt
LEAVE} are allowed in an {\tt INTERPRET}, even when they refer to a
loop that is external to the interpreted string.

Most of the time, {\tt INTERPRET} is not needed, although it can yield
compact and interesting code. If you do not strictly need {\tt
INTERPRET}, you should consider not using it, for reasons of
compatibility, speed, and readability. Many of the traditional uses of
{\tt INTERPRET} have been replaced by other mechanisms in order to
decrease the necessity of {\tt INTERPRET}; e.g.~indirect
specification\index{variables!indirectly named} of variables in
\ttidx{EXPOSE} and \ttidx{DROP}, the improved \ttidx{VALUE()} built-in
function, and indirect specification of patterns in
templates\index{template!pattern}.

Only semicolon ({\tt ;}) is allowed as a clause delimitor in the
string interpreted by an {\tt INTERPRET} instruction. The colon of
labels can not be used, since labels are not allowed. Nor does
specific end-of-line character sequences have any defined meaning
there. However, most interpreters probably allow the end-of-line
character sequence of the host operating system as alternative clause
delimitors. It is interesting to note that in the context of the {\tt
INTERPRET} instruction, an implicit, trailing clause delimitor is
always appended to the string to be interpreted.
\index{INTERPRET@{\ptt INTERPRET}|)}


\subsection{The {\tt ITERATE} Instruction}
\label{inst:iterate}
\begin{syntax}
   ITERATE $[$ {\it symbol} $]$ ;
\end{syntax}
\index{ITERATE@{\ptt ITERATE}|(bold}

The {\tt ITERATE} instruction will iterate the innermost, active
loop\index{loop} in which the {\tt ITERATE} instruction is located. If
{\it symbol} is specified, it will iterate the innermost, active loop
having {\it symbol} as control variable\index{variable!control}.  The
simple \ttidx{DO}/\ttidx{END} statement without a {\it repetitor} and
{\it conditional} is not affected by {\tt ITERATE}. All active
multiclause structures ({\tt DO}, {\tt SELECT}, and {\tt IF}) within
the loop being iterated are terminated.

The effect of an {\tt ITERATE} is to immediately transfer control to
the {\tt END} statement of the affected loop, so that the next (if
any) iteration of the loop can be started.  It only affects loops on
the current procedural level. All actions normally associated with the
end of an iteration is performed.

Note that {\it symbol} must be specified literally; i.e.\ tail
substitution\index{tail substitution} is not performed for compound
variables\index{variable!compound}. So if the control variable in the
{\tt DO} instruction is {\tt FOO.BAR}, then {\it symbol} must use
{\tt FOO.BAR} if it is to refer to the control variable, no
matter the value of the {\tt BAR} variable.

Also note that {\tt ITERATE} (and \ttidx{LEAVE}) are means of
transferring control in the program, and therefore they are related to
{\ttidx{SIGNAL}}, but they do have the effect of automatically
terminating all active loops on the current procedural level, which
{\tt SIGNAL} has.

Two types of errors can occur. Either {\it symbol} does not refer to
any loop active at the current procedural level; or (if {\it symbol}
is not specified) there does not exist any active loops at the current
procedural level.  Both errors are reported as {\tt SYNTAX} condition
{\syntaxerror{28}}.
\index{ITERATE@{\ptt ITERATE}|)}



\subsection{The {\tt LEAVE} Instruction}
\begin{syntax}
   LEAVE $[$ {\it symbol} $]$ ;
\end{syntax}
\index{LEAVE@{\ptt LEAVE}|(bold}

This statement terminates the innermost, active loop\index{loop}. If
{\it symbol} is specified, it terminates the innermost, active loop
having {\it symbol} as control variable. As for scope, syntax, errors,
and functionality, it is identical to {\tt ITERATE}, except that {\tt
LEAVE} terminates the loop, while {\tt ITERATE} lets the loop start on
the next iteration normal iteration. No actions normally associated
with the normal end of an iteration of a loop is performed for a {\tt
LEAVE} instruction.
%
\begin{example}[Iterating a simple {\tt DO}/{\tt END}]
In order to circumvent this, a simple {\tt DO}/{\tt END} can be
rewritten as this:
\begin{quote}
\begin{verbatim}
if foo then do until 1
   say 'This is a simple DO/END group'
   say 'but it can be terminated by'
   leave
   say 'iterate or leave'
   end
\end{verbatim}
\end{quote}
This shows how {\tt ITERATE} has been used to terminate what for all
practical purposes is a simple {\tt DO}/{\tt END} group. Either {\tt
ITERATE} or {\tt LEAVE} can be used for this purpose, although {\tt
LEAVE} is perhaps marginally faster.
\end{example}

\index{LEAVE@{\ptt LEAVE}|)}


\subsection{The {\tt NOP} Instruction}
\begin{syntax}
   NOP ;
\end{syntax}
\index{NOP@{\ptt NOP}|(bold}
\index{no operation|see{\rm \tt NOP}}

The {\tt NOP} instruction is the ``no operation'' statement; it 
does nothing. Actually, that is not totally true, since the {\tt NOP}
instruction is a ``real'' statement (and a placeholder), as opposed to
null clauses. I've only seen this used in two circumstances.

\begin{itemize}
\item
   After any \ttidx{THEN} or \ttidx{ELSE} keyword, where a
   statement is required, when the programmer wants an empty {\tt THEN}
   or {\tt ELSE} part. By the way, this is the intended use of {\tt NOP}.
   Note that you can not use a null clause\index{null clause} there
   (label\index{label}, comment\index{comment}, or empty lines), since
   these are not parsed as ``independant'' statements.

\item
   I have seen it used as ``trace-bait''. That is, when you start
   interactive trace\index{trace!interactive}, the statement
   immediately after the \ttidx{TRACE} instruction will be executed
   before you receive interactive control.  If you don't want that to
   happen (or maybe the {\tt TRACE} instruction was the last in the
   program), you need to add an extra dummy statement.  However, in
   this context, labels and comments can be used, too.
   \index{NOP@{\ptt NOP}|)}
\end{itemize}




\subsection{The {\tt NUMERIC} Instruction}
\label{inst:numeric}
\begin{syntax}
\begin{tabbing}
   NUMERIC \= DIGITS $[$ {\it expr} $]$ ;\\
           \> FORM $[$ SCIENTIFIC $|$ ENGINEERING $|$ $[$ VALUE $]$ 
                                                {\it expr} $]$ ;\\
           \> FUZZ $[$ {\it expr} $]$ ;
\end{tabbing}
\end{syntax}

\index{NUMERIC@{\ptt NUMERIC}|(bold}
\index{DIGITS@{\ptt DIGITS}}
\index{FORM@{\ptt FORM}}
\index{FUZZ@{\ptt FUZZ}}
\index{SCIENTIFIC@{\ptt SCIENTIFIC}}
\index{ENGINEERING@{\ptt ENGINEERING}}
\index{VALUE@{\ptt VALUE}!{\tt NUMERIC}}
{\rexx} has an unusual form of arithmetic\index{arithmetic}.  Most
programming languages use integer and floating point arithmetic,
where numbers are coded as bits in the computers native memory
words. However, {\rexx} uses floating point arithmetic of arbitrary
precision, that operates on strings representing the numbers. Although
much slower, this approach gives lots of interesting functionality.
Unless number-crunching is your task, the extra time spent by the
interpreter is generally quite acceptable and often almost
unnoticable. 

The {\tt NUMERIC} statement is used to control most aspects of
arithmetic operations. It has three distinct forms: {\tt DIGITS}, {\tt
FORM} and {\tt FUZZ}; which to choose is given by the second token in
the instruction:
\begin{description}
\item[{\tt DIGITS}]
   is used to set the number of significant
   digits\index{digits!significant} in arithmetic operations. The
   initial value is 9, which is also the default value if {\it expr}
   is not specified. Large values for {\tt DIGITS} tend to slow down
   some arithmetic operations considerably. If specified, {\it expr}
   must be a positive integer.

\item[{\tt FUZZ}]
   is used in numeric comparisons\index{comparisions!numeric}, and its
   initial and default value is 0. Normally, two numbers must have
   identical numeric values for a number of their most significant
   digits in order to be considered equal. How many digit are
   considered is determined by {\tt DIGITS}. If {\tt DIGITS} is 4,
   then 12345 and 12346 are equal, but not 12345 and 12356.  However,
   when {\tt FUZZ} is non-zero, then only the {\tt DIGITS} minus {\tt
   FUZZ} most significant digits are checked. E.g. if {\tt DIGITS} is
   4 and {\tt FUZZ} are 2, then 1234 and 1245 are equal, but not 1234
   and 1345.

   The value for {\tt FUZZ} must be a non-negative integer, and less
   than the value of {\tt DIGITS}. {\tt FUZZ} is seldom used, but is
   useful when you want to make comparisions less influenced by
   inaccuracies.  Note that using with values of {\tt FUZZ} that is
   close to {\tt DIGITS} may give highly surprising results.

\item[{\tt FORM}]
   is used to set the form in which exponential numbers are written.
   It can be set to either {\tt SCIENTIFIC} or {\tt ENGINEERING}. The
   former uses a matissa in the range 1.000... to 9.999..., and an
   exponent which can be any integer; while the latter uses a matissa
   in the range 1.000... to 999.999..., and an exponent which is
   dividable by 3. The initial and default setting is {\tt
   SCIENTIFIC}. Following the subkeyword {\tt FORM} may be the
   subkeywords {\tt SCIENTIFIC} and {\tt ENGINEERING}, or the
   subkeyword {\tt VALUE}. In the latter case, the rest of the
   statement is considered an expression, which will evaluate to
   either {\tt SCIENTIFIC} or {\tt ENGINEERING}.  However, if the
   first token of the expression following {\tt VALUE} is neither a
   symbol nor literal string, then the {\tt VALUE} subkeyword can be
   omitted.
\end{description}

The setting of {\tt FORM} never affects the decision about whether to
choose exponential form\index{exponential form} or normal floating
point form; it only affects the appearence of the exponential form
once that form has been selected.

Many things can be said about the usefulness of {\tt FUZZ}. My
impression is that it is seldom used in {\rexx} programs. One problem
is that it only addresses relative inaccurance: i.e.~that the smaller
value must be within a certain range, that is determined by a
percentage of the larger value. Often one needs absolute inaccurance,
e.g.~two measurements are equal if their difference are less than a
certain absolute treshold.

\begin{example}[Simulating relative accuracy with absolute accuracy]\hfill\\
As explained above, {\rexx} arithmetic has only relative accuracy, in
order to obtain absolute accuracy, one can use the following trick:
\begin{quote}
\begin{verbatim}
numeric fuzz 3
if a=b then 
   say 'relative accuracy'

if abs(a-b)<=500 then 
   say 'absolute accuracy'
\end{verbatim}
\end{quote}
In the first {\tt IF} instruction, if {\tt A} is 100\,000, then the
range of values for {\tt B} which makes the expression true is
99\,500--100,499, i.e.\ an inaccuracy of about +-500. If {\tt A} has
the value 10\,000\,000, then {\tt B} must be withing the range 
9\,950\,000--10\,049\,999; i.e.\ an inaccuracy of about +-50\,000. 

However, in the second {\tt IF} instruction, assuming {\tt A} is
100\,000, the expression becomes true for values of {\tt B} in the
range 99\,500--100\,500. Assuming that {\tt A} is 10\,000\,000, the
expression becomes true for values of {\tt B} in the range
9\,999\,500--10\,000\,500. 

The effect is largely to force an absolute accuracy for the second
example, no matter what the values of {\tt A} and {\tt B} are. This
transformation has taken place since an arithmetic subtraction is not
affected by the {\tt NUMERIC FUZZ}, only numeric comparison
operations. Thus, the effect of {\tt NUMERIC FUZZ} on the implicit
subtraction in the operation {\tt =} in the first {\tt IF} has been
removed by making the subtraction explict.

Note that there are some minor differences in how numbers are rounded,
but this can be fixed by transforming the expression into something
more complex.
\end{example}

To retrieve the values set for {\tt NUMERIC}, you can use the built-in
functions \ttidx{DIGITS()}, \ttidx{FORM()}, and \ttidx{FUZZ()}. These
values are saved across subroutine calls and restored upon return.
\index{NUMERIC@{\ptt NUMERIC}|)}


\subsection{The {\tt OPTIONS} Instruction}
\begin{syntax}
   OPTIONS {\it expr} ;
\end{syntax}
\index{OPTIONS@{\ptt OPTIONS}|(bold}

The {\tt OPTIONS} instruction is used to set various
interpreter-specific options. Its typical uses are to select certain
{\rexx} dialects, enable optimalizations (e.g.\ time versus memory
considerations), etc. No standard dictates what may follow the {\tt
OPTIONS} keyword, except that it should be a valid {\rexx} expression,
which is evaluated. Currently, no specific options are required by any
standard.

The contents of {\it expr} is supposed to be word based, and it is the
intension that more than one option can be specified in one {\tt
OPTIONS} instruction.  {\rexx} interpreters are specifically
instructed to ignore {\tt OPTIONS} words which they do not recognize.
That way, a program can use run-time options for one interpreter,
without making other interpreters trip when they see those options. An
example of {\tt OPTION} may be:

\begin{quote}
   \tt OPTIONS 4.00 NATIVE\_FLOAT
\end{quote}

The instuction might instruct the interpreter to start enforcing
language level 4.00, and to use native
floating point numbers in stead of the {\rexx} arbitrary precision
arithmetics.  On the other hand, it might also be completely ignored
by the interpreter.

It is uncertain whether modes selected by {\tt OPTIONS} will be saved
across subroutine calls. Refer to implementation-specific
documentation for information about this.

\begin{example}[Drawback of {\tt OPTIONS}]
Unfortunately, the processing of the {\tt OPTIONS} instruction 	has a
drawback. Since an interpreter is instructed to ignore option-settings
that it does not understand, it may ignore options which are essential
for further processing of the program. Continuing might cause a fatal
error later, although the behavior that would most precisely point out
the problem is a complaint about the non-supported {\tt OPTION}
setting. Consider
\begin{quote}
\begin{verbatim}
options 'cms_bifs'
pos = find( haystack, needle )
\end{verbatim}
\end{quote}
If this code fragment is run on an interpreter that does not support
the {\tt cms\_bifs} option setting, then the {\tt OPTIONS} instruction
may still seem to have been executed correctly.  However, the second
clause will generally crash, since the {\tt FIND()} function is still
not available. Even though the real problem is in the first line,
the error message is reported for the second line.
\end{example}
\index{OPTIONS@{\ptt OPTIONS}|)} 




\subsection{The {\tt PARSE} Instruction}
\label{inst:parse}
\begin{syntax}
   PARSE $[$ UPPER $]$ {\it type} $[$ {\it template} $]$ ;
\begin{quote}
\begin{tabbing}
   {\it type} = \= $\{$ ARG $|$ LINEIN $|$ PULL $|$ SOURCE $|$ VERSION $\}$\\
                \> VALUE $[$ {\it expr} $]$ WITH\\
                \> VAR {\it symbol}
\end{tabbing}
\end{quote}
\end{syntax}

The {\tt PARSE} instruction takes one or more source strings, and then
parses them using the {\it template\/} for directions. The process of
parsing is one where parts of a source string are extracted and stored
in variables. Exactly which parts, is determined by the patterns.  A
complete description of parsing is given in chapter [not yet written].

Which strings are to be the source of the parsing is defined by the
{\it type\/} subclause, which can be any of:
\begin{description}
\item[{\tt ARG}.]
   The data to use as the source during the parsing is the argument
   strings given at the invocation of this procedure level. Note that
   this is the only case where the source may consist of multiple
   strings.

\item[{\tt LINEIN}.]
   Makes the {\tt PARSE} instruction read a line from the standard
   input stream, as if the {\tt LINEIN()} built-in function had been
   called. It uses the contents of that line (after stripping off
   end-of-line characters, if necessary) as the source for the
   parsing. This may raise the {\tt NOTREADY} condition if problems
   occurred during the read.

\item[{\tt PULL}.]
   Retrieves as the source string for the parsing the topmost line
   from the stack. If the stack is empty, the default action for
   reading an empty stack is taken. That is, it will read a whole line
   from the standard input stream, strip off any end-of-line
   characters (if necessary), and use that string as the source. 

\item[{\tt SOURCE}.]
   The source string for the parsing is a string containing
   information about how this invocation of the {\rexx} interpreter
   was started. This information will not change during the execution
   of a {\rexx} script. The format of the string is:
\begin{quote}\tt
   {\it system} {\it invocation} {\it filename}
\end{quote}
   Here, the first space-separated word ({\it system\/}) is a single
   word describing the platform on which the system is running. Often,
   this is the name of the operating system. The second word describes
   how the script was invoked. \cite{trl2} suggests that {\it
   invocation} could be {\tt COMMAND}, {\tt FUNCTION}, or {\tt
   SUBROUTINE}, but notes that this may be specific to VM/CMS.

   Everything after the second word is implementation-dependant. It is
   indicated that it should refer to the name of the {\rexx} script,
   but the format is not specified. In practice, the format will
   differ because the format of file names differs between various
   operating systems. Also, the part after the second word might
   contain other types of information. Refer to the
   implementation-specific notes for exact information.

\item[{\tt VALUE {\it expr} WITH}.]
   This form will evaluate {\it expr} and use the result of that
   evaluation as the source string to be parsed. The token {\tt WITH}
   may not occur inside {\it expr}, since it is a reserved subkeyword
   in this context.

\item[{\tt VAR {\it symbol}}.]
   This form uses the current value of the named variable {\it
   symbol} (after tail-substitution) as the source string to
   be parsed.  The variable may be any variable symbol. If the
   variable is uninitialized, then a {\tt NOTREADY} condition will be
   raised.

\item[{\tt VERSION}.]
   This format resembles {\tt SOURCE}, but it contains information
   about the version of {\rexx} that the interpreter supports. The
   string contains five words, and has the following format:
\begin{quote}\tt
   {\it language} {\it level} {\it date} {\it month} {\it year}
\end{quote}
   Where {\it language} is the name of the language supported by the
   {\rexx} interpreter. This may seem like overkill, since the
   language is {\rexx}, but there may be various different dialects of
   {\rexx}. The word can be just about anything, except for two
   restrictions, the first four letters should be {\tt REXX} (in upper
   case), and the word should not contain any periods. \cite{trl2}
   indicates that the remaineder of the word (after the fourth
   charater) can be used to identify the implementation.

   The second word is the {\rexx} language level supported by the
   interpreter. Note that this is not the same as the version of the
   interpreter, although several implementations makes this mistake.
   Strictly speaking, neither \cite{trl1} nor \cite{trl2} define the
   format of this word, but a numeric format is strongly suggested.

   The last three words ({\it date}, {\it month}, and {\it year\/})
   makes up the date part of the string.  This is the release
   date of the interpreter, in the default format of the {\tt DATE()}
   built-in function.
\end{description}
Much confusion seems to be related to the second word of {\tt PARSE
VERSION}. It describes the language level, which is not the same as
the version number of the interpreter. In fact, most interpreters have
a version numbering which is independant of the {\rexx} language
level. Unfortunately, several interpreters makes the mistake of using
this field as for their own version number. This is very unfortunate
for two reasons; first, it is incorrect, and second, it makes it
difficult to determine which {\rexx} language level the interpreter is
supposed to support.

Chances are that you can find the interpreter version number in {\tt
PARSE SOURCE} or the first word of {\tt PARSE VERSION}.

The format of the {\rexx} language level is not rigidly defined, but
\cite{trl1} corresponds to the language level 3.50, while \cite{trl2}
corresponds to the language level 4.00. Both implicitly indicate the
that language level description is a number, and states that an
implementation less than a certain number ``may be assumed to indicate
a subset'' of that language level. However, this must not be taken to
literally, since language level 3.50 has at least two features which
are missing in language level 4.00 (the {\tt Scan} trace setting, and
the {\tt PROCEDURE} instruction that is not forced to be the first
instruction in a subroutine). {\cite{trh:price}} gives a very good
overview over the varying functionality of different language levels
of {\rexx} up to level 4.00.

Note that even though the information of the {\tt PARSE SOURCE} is
constant throughout the execution of a {\rexx} script, this is not
necessarily correct for the {\tt PARSE VERSION}. If your interpreter
supports multiple language levels (e.g.\ through the {\tt OPTIONS}
instruction), then it will have to change the contents of the {\tt
PARSE VERSION} string in order to comply with different language
levels. To some extent, this may also apply to {\tt PARSE SOURCE},
since it may have to comply with several implementation-specific
standards.

After the source string has been selected by the {\it type} subclause
in the {\tt PARSE} instruction, this string is parsed into the
template. The functionality of templates is common for the {\tt PARSE},
{\tt ARG} and {\tt PULL} instructions, and is further explained in
chapter [not yet written]. 



\subsection{The {\tt PROCEDURE} Instruction}
\begin{syntax}
   PROCEDURE $[$ EXPOSE $[$ {\it varref} $[$ {\it varref} ... $] ] ]$ ;
\begin{quote}
\begin{tabbing}
   varref = { {\it symbol} | ( {\it symbol} ) }
\end{tabbing}
\end{quote}
\end{syntax}
\index{PROCEDURE@{\ptt PROCEDURE}|(bold}
\index{EXPOSE@{\ptt EXPOSE}|(bold}
\index{subroutine|(bold}

The {\tt PROCEDURE} instruction is used by {\rexx}
subroutines\index{subroutine} in order to control how variables are
shared among routines. The simplest use is without any parameters;
then all future references to variables in that subroutine refer to
local variables.\index{variables!local}\index{variables!global} If
there is no {\tt PROCEDURE} instruction in a subroutine, then all
variable references in that subroutine refer to variables in the
calling routine's name space\index{name space}.

If the {\tt EXPOSE} subkeyword is specified too, then any references
to the variables in the list following {\tt EXPOSE} refer to
local variables, but to variables in the name space\index{name space}
of the calling routine.  

\begin{example}[Dynamic excution of {\tt PROCEDURE}]
The definition opens for some strange effects, consider the following
code:
\begin{quote}
\begin{verbatim}
call testing

testing:
   say foo
   procedure expose bar
   say foo
\end{verbatim}
\end{quote}
Here, the first reference to {\tt FOO} is to the variable {\tt FOO} in
the caller routine's name space, while the second reference to {\tt
FOO} is to a local variable\index{variable!local} in the called
routine's name space. This is difficult to parse statically, since the
names to expose\index{variable!exposed} (and even when to expose them)
is determined dynamically during run-time.  Note that this use of
{\tt\ PROCEDURE} is allowed in TRL1, but not in TRL2.
\end{example}

Several restrictions have been imposed on {\tt PROCEDURE} in TRL2 in
order to simplify the execution of {\tt PROCEDURE} (and in particular,
to ease the implementation of optimizing\index{optimalization}
interpreters and compilers\index{compilers}).

\begin{itemize}
\item
   The first restriction, to which all {\rexx} interpreters adhere as
   far as I know, is that each invocation of a subroutine (i.e.~not
   the main program) may execute {\tt PROCEDURE} at most once. Both
   TRL1 and TRL2 contain this restriction. However, more than one {\tt
   PROCEDURE} instruction may exist ``in'' each routine, as long as at
   most one is executed at each invocation of the subroutine.

\item
   The second restriction is that the {\tt PROCEDURE} instruction must be
   the first statement in the subroutine. This restriction was introduced
   between {\rexx} language level 3.50 and 4.00, but several level 4.00
   interpreters may not enforce it, since there is no breakage when
   allowing it. 
\end{itemize}

There are several important consequences of this second restriction:
(1) it implicitly includes the first restriction listed above, since
only one instruction can be the first; (2) it prohibits selecting one
of several possible {\tt PROCEDURE} instructions; (3) it prohibits
using the same variable name twice; first as an exposed and then as a
local variable, as indicated in the example above; (4) it prohibits
the customary use of {\tt PROCEDURE} and {\tt INTERPRET}, where the
latter is used to create a level of
indirectness\index{variable!indirectly named} for the {\tt PROCEDURE}
instruction.  This particular use can be exemplified by:
\begin{verbatim}
   testing:
      interpret 'procedure expose' bar
\end{verbatim}
where {\tt BAR} holds a list of variable names which are to be exposed.
However, in order to make this functionality available without having
to resort to \ttidx{INTERPRET}, which is generally considered ``bad''
programming style, new functionality has been added to {\tt PROCEDURE}
between language levels 3.50 and 4.00. If one of the variables in the
list of variables is enclosed in parantheses, that means
indirection\index{indirection|see{\rm variable, indirectly named}}.
Then, the variables exposed are: (1) the cariable enclosed in
parantheses; (2) the value of that variable is read, and its contents
is taken to be a space-separated list of variable names; and (3) all
there variable names are exposed strictly in order from left to right. 

\begin{example}[Indirect exposing]
Consider the following example:
\begin{verbatim}
   testing:
      procedure expose foo (bar) baz
\end{verbatim}
Assuming that the variable {\tt BAR} holds the value {\tt one two},
then variables exposed are the following: {\tt FOO}, {\tt BAR}, {\tt
ONE}, {\tt TWO}, {\tt BAZ}, in that order. In particular, note that
the variable {\tt FOO} is exposed immediately before the variables
which it names are exposed.
\end{example}

\begin{example}[Order of exposing]
Then there is another fine point about exposing, the variables are
hidden immediately after the {\tt EXPOSE} subkeyword, so they are not
initially available when the variablelist is processed. Consider the
following code:
\begin{verbatim}
   testing:
      procedure expose bar foo.bar foo.baz baz
\end{verbatim}
which exposes variables in the order specified. If the variable {\tt
BAR} holds the value {\tt 123}, then {\tt FOO.123} is exposed as the
second item, since {\tt BAR} is visible after having already been
exposed as the first item. On the other hand, the third item will
always expose the variable {\tt FOO.BAZ}, no matter what the value
of\/ {\tt BAZ} is in the caller, since the {\tt BAZ} variable is
visible only after it has been used in the third item. Therefore, the
order in which variables are exposed is important. So, if a compound
variable\index{variable!compound} is used inside parentheses in an
{\tt PROCEDURE} instruction, then any simple symbols needed for tail
substitution\index{tail substitution} must previously to have been
explicitly exposed. Compare this to the {\tt DROP} instruction.
\end{example}

What exactly is exposing? Well, the best description is to say that it
makes all future uses (within that procedural level) to a particular
variable name refer to the variable in the calling routine rather than
in the local subroutine. The implication of this is that even if it is
dropped\index{dropping} or it has never been set\index{value!initial},
an exposed variable will still refer to the variable in the calling
routine.  Another important thing is that it is the tail-substituted
variable name that is exposed. So if you expose {\tt FOO.BAR}, and
{\tt BAR} has the value {\tt 123}, then only {\tt FOO.123} is exposed,
and continues to be so, even if {\tt BAR} later changes its value to
e.g.~{\tt 234}.

\begin{example}[Global variables]
A problem lurking on new {\rexx} users, is the fact that exposing a
variable only exposes it to the calling routine. Therefore, it is
incorrect to speak of global variables, since the variable might be
local to the calling routine. To illustrate, consider the following
code:
\begin{verbatim}
   foo = 'bar'
   call sub1
   call sub2
   exit

   sub1: procedure expose foo
      say foo  /* first says 'bar', then 'FOO' */
      return 

   sub2: procedure
      say foo  /* says 'FOO' */
      call sub1
      return
\end{verbatim}
Here, the first subroutine call in the ``main'' program writes out
{\tt bar}, since the variable {\tt FOO} in {\tt SUB1} refers to the
{\tt FOO} variable in the main program's (i.e.~its caller routine's)
name space. During the second call from the main program, {\tt SUB2}
writes out\/ {\tt FOO}, since the the variable is not exposed.
However, {\tt SUB2} calls {\tt SUB1}, which exposes {\tt FOO}, but
that subroutine also writes out {\tt FOO}. The reason for this is
that\/ {\tt EXPOSE} works on the run-time nesting of routines, not on
the typographically structure of the code. So the {\tt PROCEDURE} in
{\tt SUB1} (on its second invocation) exposes {\tt FOO} to {\tt SUB2},
not to the main program as typography might falsely indicate.
\end{example}

The often confusing consequence of the run-time binding of variable
names is that an exposed variable of {\tt SUB1} can be bound to
different global variables, depending on from where it was called.
This differs from most compiled languages, which bind their variables
independantly of from where a subroutine is called. In turn, the
consequence of this is that {\rexx} has severe problems storing a
persistent, static variable\index{variable!static} which is needed by
one subroutine only. A subroutine needing such a variable (e.g.~a
count variable which is incremented each time the subroutine is
called), must either use an operating system command\index{command},
or all subroutines calling that subroutine (and their calling
routines, etc) must expose the variable. The first of these solution
is very inelegant and unstandard, while the second is at best
troublesome and at worst seriously limits the maximum practial size of
a {\rexx} program.  There are hopes that the {\tt VALUE()} built-in
function will fix this in future standards of {\rexx}.

Another important drawback with {\tt PROCEDURE} is that it only works
for internal subroutines; for external subroutines it either do not
work, or {\tt PROCEDURE} may not even be allowed on the main level of
the external subroutine. However, in internal subroutines inside the
external subroutines, {\tt PROCEDURE} is allowed, and works like
usual.
\index{PROCEDURE@{\ptt PROCEDURE}|)}
\index{EXPOSE@{\ptt EXPOSE}|)}
\index{subroutine|)}




\subsection{The {\tt PULL} Instruction}
\begin{syntax}
   PULL $[$ {\it template} $]$ ;
\end{syntax}
\label{inst:pull}

This statement takes a line from the top of the stack and
parse it into the variables in the {\it template}. It will also
translate the contents of the line to uppercase.

This statement is equivalent to {\tt PARSE UPPER PULL [{\it
template}]} with the same exception as explained for the {\tt ARG}
instruction. See chapter [not yet written] for a description of parsing
and chapter \ref{ch:stack} for a discussion of the stack.



\subsection{The {\tt PUSH} Instruction}
\label{inst:push}
\begin{syntax}
   PUSH $[$ {\it expr} $]$ ;
\end{syntax}

The {\tt PUSH} instruction will add a string to the stack. The string
added will either be the result of the {\it expr}, or the nullstring
if {\it expr} is not specified. 

The string will be added to the top of the stack (LIFO), i.e.~it will
be the first line normally extracted from the stack. For a thorough
discussion of the stack and the methods of manipulating it, see
chapter \ref{ch:stack} for a discussion of the stack.



\subsection{The {\tt QUEUE} Instruction}
\begin{syntax}
   QUEUE $[$ {\it expr} $]$ ;
\end{syntax}
\label{inst:queue}

The {\tt QUEUE} instruction is identical to the {\tt PUSH}
instruction, except for the position in the stack where the new line
is inserted. While the {\tt PUSH} puts the line on the ``top'' of the
stack, the {\tt QUEUE} instruction inserts it at the bottom of the
stack (FIFO), or in the bottom of the topmost buffer, if buffers are
used. 

For further information, refer to documentation for the {\tt PUSH}
instruction, and see chapter \ref{ch:stack} for general information
about the stack.



\subsection{The {\tt RETURN} Instruction}
\begin{syntax}
   RETURN $[$ {\it expr} $]$ ;
\end{syntax}

The {\tt RETURN} instruction is used to terminate the current
procedure level, and return control to a level above. When {\tt
RETURN} is executed inside one or more nesting construct, i.e.\ {\tt
DO}, {\tt IF}, {\tt WHEN}, or {\tt OTHERWISE}, then the nesting
constructs (in the procedural levels being terminated) are terminated
too.

Optionally, an expression can be specified as an argument to the {\tt
RETURN} instruction, and the string resulting from evaluating this
expression will be the return value from the procedure level
terminated to the caller procedure level. Only a single value can be
returned. When {\tt RETURN} is executed with no argument, no return
value is returned to the caller, and then a {\tt SYNTAX} condition
{\syntaxerror{44}} is raised if the subroutine was invoked as a
function.

\begin{example}[Multiple entry points]
A routine can have multiple exit points, i.e.\ a procedure can be
terminated by any of several {\tt RETURN} instructions.  A routine can
also have multiple entry points, i.e.\ several routine entry points
can be terminated by the same {\tt RETURN} instruction.  However, this
is rarer than having multiple exit points, because it is generally
perceived that it creates less structured and readable code. Consider
the following code:
\begin{quote}
\begin{verbatim}
call foo
call bar
call baz
exit

foo: 
   if datatype(name,'w') then
      drop name
   signal baz 

bar: 
   name = 'foo'

baz:
   if symbol('name')=='VAR' then
      say 'NAME currently has the value' name
   else
      say 'NAME is currently an unset variable'
   return
\end{verbatim}
\end{quote}
Although this is hardly a very practical example, it shows how the
main bulk of a routine can be used together with three different entry
points. The main part of the routine is the {\tt IF} statement having
two {\tt SAY} statements. It can be invoked by calling {\tt FOO}, {\tt
BAR}, or {\tt BAZ}. 

There are several restrictions to this approach. For instance, the
{\tt PROCEDURE} statement becomes cumersome, but not impossible, to
use.

Also note that when a routine has multiple exit points, it may choose
to return a return value only at some of those exit points.
\end{example}

When a routine is located at the very end of a source file, there is
an implicit {\tt RETURN} instruction after the last explicit clause.
However, according to good programming practice, you should avoid
taking advantage of this feature, because it can create problems later
if you append new routines to the source file and forget to change the
implied {\tt RETURN} to an explicit one.

If the current procedure level is the main level of either the program
or an external subroutine, then a {\tt RETURN} instruction is
equivalent to an {\tt EXIT} instruction, i.e.\ it will terminate the
{\rexx} program or the external routine.  Table \ref{tab:rexit} shows
the actions of both the {\tt RETURN} and {\tt EXIT} instructions
depending on the context in which they occur.



\subsection{The {\tt SAY} Instruction}
\begin{syntax}
   SAY $[$ {\it expr} $]$ ;
\end{syntax}

Evaluates the expression {\it expr}, and prints the resulting string
on the standard output stream. If {\it expr} is not specified, the
nullstring is used instead. After the string has been written, an
implementation-specific action is taken in order to produce an
end-of-line.

The {\tt SAY} instruction is roughly equivalent to
\begin{verbatim}
   call lineout , expr
\end{verbatim}
The differences are that there is no way of determining whether the
printing was successfully completed if {\tt SAY} is used, and the
special variable {\tt RESULT} is never set when executing a {\tt SAY}
instruction. Besides, the effect of ommitting {\it expr} is different.
In SAA API, the {\tt RXSIOSAY} subfunction of the {\tt RXSIO} exit
handler is able to trap a {\tt SAY} instruction, but not a call to the
{\tt LINEOUT()} built-in function. Further, the {\tt NOTREADY}
conditon is never raised for a {\tt SAY} instruction.



\subsection{The {\tt SELECT}/{\tt WHEN}/{\tt OTHERWISE} Instruction}
\begin{syntax}
   SELECT ; {\it whenpart} $[$ {\it whenpart} ... $]$ $[$ OTHERWISE $[$;$]$ 
                                 $[$ {\it statement} ... $]$ $]$ END ;
\begin{quote}
   {\it whenpart} : WHEN {\it expr} $[$;$]$ THEN $[$;$]$ {\it statement}
\end{quote}
\end{syntax}

This instruction is used for general purpose, nested {\tt IF}
structures. Although it has certain similarities with {\tt CASE} in
Pacsal and {\tt switch} in C, it is in some respects very different
from these. An example of the general use of the {\tt SELECT}
instruction is:
\begin{verbatim}
   select
      when expr1 then statement1
      when expr2 then do
         statement2a
         statement2b
         end
      when expr3 then statement3
      otherwise
         ostatement1
         ostatement2
      end
\end{verbatim}

When the {\tt SELECT} instruction is executed, the next statement
after the {\tt SELECT} statement must be a {\tt WHEN} statement. The
expression immediately following the {\tt WHEN} token is evaluated,
and must result in a valid boolean value. If it is true (i.e.~{\tt
1}), the statement following the {\tt THEN} token matching the {\tt
WHEN} is executed, and afterwards, control is transferred to the
instruction following the {\tt END} token matching the {\tt SELECT}
instruction. This is not completely true, since an instruction may
transfer control elsewhere, and thus implicitly terminate the {\tt
SELECT} instruction; e.g.~{\tt LEAVE}, {\tt EXIT}, {\tt ITERATE}, {\tt
SIGNAL}, or {\tt RETURN} or a condition trapped by method {\tt
SIGNAL}.

If the expression of the first {\tt WHEN} is not true (i.e.~`{\tt 0}),
then the next statement must be either another {\tt WHEN} or an {\tt
OTHERWISE} statement. In the former case, the process explained
above is iterated. In the latter case, the clauses following the {\tt
OTHERWISE} up to the {\tt END} statement are interpreted. 

It is considered a {\tt SYNTAX} condition, {\syntaxerror{7}} if no
{\tt OTHERWISE} statement when none of the {\tt WHEN}-expressions
evaluates to true. In general this can only be detected during
runtime. However, if one of the {\tt WHEN}s is selected, the absence
of an {\tt OTHERWISE} is not considered an error.

By the nature of the {\tt SELECT} instruction, the {\tt WHEN}s are
tested in the sequence they occur in the source. If more than one {\tt
WHEN} have an expression that evaluates to true, the first one
encountered is selected.

If the programmer wants to associate more than one statement with a
{\tt WHEN} statement, a {\tt DO/END} pair must be used to enclose the
statements, to make them one statement conceptually. However, zero,
one, or more statements may be put after the {\tt OTHERWISE} without
having to enclose them in a {\tt DO}/{\tt END} pair. The clause
delimitor is optional after {\tt OTHERWISE}, and before and after {\tt
THEN}.

\begin{example}[Writing {\tt SWITCH} as {\tt IF}]
Although {\tt CASE} in Pascal and {\tt switch} in C are in general
tabel-driven (they check an integer constant and jumps directly to the
correct {\tt case}, based on the value of the constant), {\tt SELECT}
in {\rexx} is not so. It is a just a shorthand notation for nested
{\tt IF} instructions. Thus a {\tt SWITCH} instruction can always be
written as set of nested {\tt IF} statements; but for very large
{\tt SWITCH} statements, the corresponding nested {\tt IF} structure
may be too deeply nested for the interpreter to handle. 

The following code shows how the {\tt SWITCH} statement shown above
can be written as a nested {\tt IF} structure:
\begin{verbatim}
   if expr1 then statement1
   else if expr2 then do
      statement2a
      statement2b
      end
   else if expr3 then statement3
   else 
      ostatement1
      ostatement2
   end
\end{verbatim}
\end{example}



\subsection{The {\tt SIGNAL} Instruction}
\begin{syntax}
\begin{tabbing}
   SIGNAL \= \{ {\it string} | {\it symbol} \} ;\\ 
          \> $[$ VALUE $]$ {\it expr} ;\\
          \> $\{$ ON $|$ OFF $\}$ {\it condition} $[$ NAME
                                   \{ {\it string} | {\it symbol} \} $]$ ;
\end{tabbing}
\end{syntax}

The {\tt SIGNAL} instruction is used for two purposes: (a) to transfer
control to a named label in the program, and (b) to set up a named
condition trap.

The first form in the syntax definition transfers control to the named
label, which must exist somewhere in the program; if it does not
exist, a {\tt SYNTAX} condition {\syntaxerror{16}} is raised. If the
label is multiple defined, the first definition is used. The parameter
can be either a symbol (which is taken literally) or a string. If it
is a string, then be sure that the case of the string matches the case
of the label where it is defined. In practice, labels are in upper
case, so the string should contain only uppercase letters too, and no
space characters.

The second form of the syntax is used if the second token of the
instruction is {\tt VALUE}. Then, the rest of the instruction is taken
as a general {\rexx} expression, which result after evaluation is
taken to be the name of the label to transfer control to. This form is
really just a special case of the first form, where the programmer is
allowed to specify the label as an expression. Note that if the start
of {\tt expr} is such that it can not be misinterpreted as the first
form (i.e.~the first token of {\it expr\/} is neither a string nor a
symbol), then the {\tt VALUE} subkeyword can be ommitted.

\begin{example}[Tranfering control to inside a loop]
When the control of execution is transferred by a {\tt SIGNAL}
instruction, all active loops at the current procedural level are
terminated, i.e.~they can not continued later, although they can of
course be reentered from the normal start. The consequence of this is
that the following code is illegal:
\begin{verbatim}
   do forever
      signal there
      there: nop
      end
\end{verbatim}
The fact that the jump is altogether within the loop does not prevent
the loop from being terminated. Thus, after the jump to the loop, the
{\tt END} instruction is attempted executed, which will result in a
{\tt SYNTAX} condition \syntaxerror{10}. However, if control is
tranferred out of the loop after the label, but before the {\tt END},
then it would be legal, i.e.~the following is legal:
\begin{verbatim}
   do forever
      signal there
      there: nop
      signal after
      end
   after:
\end{verbatim}
This is legal, simply because the {\tt END} instruction is never seen
during this script. Although both TRL1 and TRL2 allow this contruct,
it will probably be disallowed in ANSI.
\end{example}

Just as loops are terminated by a {\tt SIGNAL} instruction, {\tt
SELECT} and {\tt IF} instructions are also terminated. Thus, it is
illegal to jump to a location within a block of statements contained
in a {\tt WHEN}, {\tt OTHERWISE}, or {\tt IF} instruction, unless the
control is transferred out of the block before the execution reaches
the end of the block.

Whenever execution is transferred during a {\tt SIGNAL} instruction,
the special variable {\tt SIGL} is set to the line number of the line
containing the {\tt SIGNAL} instruction, before the control is
transferred. If ths instruction extends over several lines, it refers
to the first of this. Note that even blanks are part of a clause, so
if the instruction starts with a line continuation, the real line
of the instruction is different from that line where the instruction
keyword is located. 

The third form of syntax is used when the second token in the
instruction is either {\tt ON} or {\tt OFF}. In both cases must the
third token in the instruction be then name of a condition (as a
constant string or a symbol, which is taken literally), and the setup
of that condition trap is changed. If the second token is {\tt OFF},
then the trap of the named condition is disabled.

If the second token is {\tt ON}, then the trap of the named condition
is enabled. Further, in this situation two more tokens may be allowed
in the instruction: the first must be {\tt NAME} and the second must
be the name of a label (either as a constant string or a symbol, which
is taken literally). If the five token form is used, then the label of
the condition handler is set to the named label, else the name of the
condition handler is set to the default, which is identical to the
name of the condition itself. 

Note that the {\tt NAME} subclause of the {\tt SIGNAL} instruction was
a new construct in TRL2, and is not a part of TRL1. Thus, older
interpreters may not support it. 

\begin{example}[Naming condition traps]
Note that the default value for the condition handler (if the {\tt
NAME} subclause is not specified) is the name of the condition, not
the condition handler from the previous time the condition was
enabled. Thus, after the following code, the name of the condition
handler for the condition {\tt SYNTAX} is {\tt SYNTAX}, not\/ {\tt
FOOBAR}:
\begin{verbatim}
   signal on syntax name foobar
   signal on syntax
\end{verbatim}
\end{example}

\begin{example}[Named condition traps in TRL1]
A common problem when trying to port {\rexx} code from a TRL2
interpreter to a TRL1 interpreter, is that explicitly named condition
traps are not supported. There exist ways to circumvent this, like:
\begin{quote}
\begin{verbatim}
syntax_name = 'SYNTAX_HANDLER'
signal on syntax
if 1 + 2 then  /* will generate SYNTAX condition */
   nop 

syntax:
   oldsigl = sigl
   signal value translate(syntax_name)
   
syntax_handler:
   say 'condition at line' oldsigl 'is being handled...'
   exit
\end{verbatim}
\end{quote}
Here, a ``global'' variable is used to store the name of the real
condition handler, in the absence of a field for this in the
interpreter. This works fine, but there are some problems: the
variable {\tt SYNTAX\_NAME} must be exposed to everywhere, in order to
be available at all times. It would be far better if this value could
be stored somewhere from which it could be retrieved from any part of
the script, no matter the current state of the call-stack. This can be
fixed with programs like {\tt GLOBALV} under {\rm VM/CMS} and {\tt
putenv} under {\rm Unix}.

Another problem is that this destroys the possibility of setting up
the condition handler with the default handler name. However, to
circumvent this, add a new\/ {\tt DEFAULT\_SYNTAX\_HANDLER} label
which becomes the new name for the old\/ {\tt SYNTAX} label.
\end{example}

Further information about conditions and condition traps are given in
chapter \ref{ch:conditions}.


\subsection{The {\tt TRACE} Instruction}
\label{inst:trace}
\begin{syntax}
   TRACE $[$ number $|$ {\it setting} $|$ $[$ VALUE $]$ {\it expr} $]$ ;

   {\it setting} = {\tt A | S | C | E | F | I | L | N | O | R | S}
\end{syntax}

The {\tt TRACE} instruction is used to set a tracing mode. Depending
on the current mode, various levels of debugging information is
displayed for the programmer. Also interactive tracing is allowed,
where the user can reexecute clauses, change values of variables, or
in general, execute {\rexx} code interactively between the statements
of the {\rexx} script.

If {\it setting} is not specified, then the default value {\tt N} is
assumed.  If the second token after {\tt TRACE} is {\tt VALUE}, then
the remaining parts of the clause is interpreted as an expression,
which value is used as the trace setting. Else, if the second token is
either a string of a symbol, then it is taken as the trace setting;
and a symbol is taken literally. In all other circumstances, whatever
follows the token {\tt TRACE} is taken to be an expression, which
value is the trace setting. 

If a parameter is given to the {\tt TRACE} instruction, and
the second token in the instruction is not {\tt VALUE}, then there must
only be one token after {\tt TRACE}, and it must be either a constant
string or a symbol (which is taken literally). The value of this token
can be either a whole number or a tracesetting.

If is it a whole number and the number is positive, then the number
specifies how many of interactive pauses to skip. This assumes
interactive tracing; if interactive tracing is not enabled, this {\tt
TRACE} instruction is ignored. If the parameter is a whole, negative
number, then tracing is turned off temporarily for a number of clauses
determined by the absolute value of {\it number}.

If the second token is a symbol of string, but not a whole number,
then it is taken to be one of the settings below. It may optionally be
preceded by one or more question mark ({\tt ?}) characters. Of the
rest of the token, only the first letter matter; this letter is
translated to upper case, and must be one of the following:
\begin{itemize}
\item[{\tt A}]
   (All) Traces all clauses before execution. 

\item[{\tt C}]
   (Commands) Traces all command clauses before execution. 

\item[{\tt E}]
   (Errors) Traces any command that would raise the {\tt ERROR}
   condition (whether enabled or not) after execution. Both the
   command clause and the return value is traced.

\item[{\tt F}]
   (Failures) Trances any command that would raise the {\tt FAILURE}
   condition (whether enabled or not) after execution. Both the
   command clause and the return value is traced.

\item[{\tt I}]
   (Intermediate) Traces not only all clauses, but also traces all
   evaluation of expressions; even intermediate results. This is the
   most detailed level of tracing. 

\item[{\tt L}]
   (Labels) Traces the name of any label clause executed; whether the
   label was jumped to or not. 

\item[{\tt N}]
   (Normal or Negative) This is the same as the {\tt Failure} setting.

\item[{\tt O}]
   (Off) Turns off all tracing.

\item[{\tt R}]
   (Results) Traces all clauses and the results of evaluating
   expressions. However, intermediate expressions are not traced.

\item[{\tt S}]
   (Scan) Traces all clauses from the current position in the script,
   until the end of the file, in sequence. However, it does not
   execute any of the clauses. When the end of the program is reached,
   the interpreter exits. 
\end{itemize}

The {\tt Errors} and {\tt Failures} settings are not
influenced by whether the {\tt ERROR} or {\tt FAILURE} conditions are
enabled or not. These {\tt TRACE} settings will trace the command and
return value after the command have been executed, but before the
respective condition is raised. 

The levels of tracing might be set up graphically, as in figure
{\ref{fig:traceset}}. An arrow indicates that the setting pointed to
is a superset of the setting pointed from.
\begin{figure}[htb]
\begin{verbatim}
      /--> Failures --> Errors --> Commands
   Off                               \  
      \---------> Labels ---------------> All --> Results --> Intermediate
\end{verbatim}
\caption{Hierarchy of {\tt TRACE} settings}
\label{fig:traceset}
\end{figure}

According to this figure, {\tt Intermediate} is a superset of {\tt
Result}, which is a superset of {\tt All}. Further, {\tt All} is a
superset of both {\tt Commands} and {\tt Labels}. {\tt Commands} is a
superset of {\tt Errors}, which is a superset of {\tt Failures}. Both
{\tt Failure} and {\tt Labels} are supersets of {\tt Off}. Actually,
{\tt Command} is strictly speaking not a superset of {\tt Errors},
since {\tt Errors} traces after the command, while {\tt Command}
traces before the command.

{\tt Scan} is not part of this diagram, since it provides a
completely different tracing functionality. Note that {\tt Scan} is
part of TRL1, but was removed in TRL2. It is not
likely to be part of newer {\rexx} interpreters.




\section{Implementation-Specific Information}

\subsection{Environments in Regina \ReginaVersion}

\begin{description}
\item[External environments name stack]

\item[External environments names]

\item[{\tt OPTIONS} settings]
   are saved across subroutines, just like other pieces of
   information, like conditions settings, {\tt NUMERIC} settings, etc.
   See chapter \ref{ch:options} for more information about {\tt
   OPTIONS} settings.
   
\item[Return value] 
   to the program that called {\regina} is limited to being an
   integer, when this is required by the operating systems.  All
   current implementations are for operating systems that require
   this.

\item[Default return value]
   from a {\rexx} program is {\tt 0} under most systems, specifically
   Unix, OS/2, MS-DOS.  Here, VMS deviates, since it uses {\tt 1} as
   the default return value. Using {\tt 0} under VMS tends to make VMS
   issue a warning saying that no error occurred.

\item[Transferring control into a loop]
   works fine in {\regina}, as long as no {\tt END}, {\tt THEN}, {\tt
   ELSE}, {\tt WHEN}, or {\tt OTHERWISE} instructions are executed
   afterwards; unless the normal entrypoint for the construct has been
   executed after the transfer of control.

\item[{\tt PARSE SOURCE} information]

\item[{\tt PARSE VERSION} information]

\item[Last line of source code] 
   is implicitly taken to be terminated by an end-of-line sequence in
   {\regina}, even if such a sequence is not present in the source
   code of the {\rexx} script. This applies only to source code. Also,
   the end-of-string in {\tt INTERPRET} strings is taken to be
   implicitly terminated by an end-of-line character sequence. 

\item[Moving code MS-DOS to Unix] 
   is simplified by {\regina}, since it will accept the MS-DOS type
   end of line sequences as valid. I.e.\ any Ctrl-M in front of a
   Ctrl-J in the source file is ignored on Unix systems by {\regina}.
   This applies only to source code. 

\item[Labels in {\tt INTERPRET}]
   is handles by {\regina} in the following way: A label can occur
   inside an {\tt INTERPRET} string, but it is ignored, and can never
   be jumped to in a {\tt SIGNAL} or {\tt CALL} instruction.

\end{description}


\subsection{List of All Environment Names in Use}
