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


\chapter{{\rexx} Builtin Functions}

\begin{it}
This chapter describes the {\rexx} library of builtin functions. It
is divided into three parts:

\begin{enumerate}
\item
   First a general introduction to builtin functions, pointing out
   concepts, fitfalls, parameter conventions, pecularities, and
   possible system dependencies. 

\item
   Then there is the reference section, which describes in detail each
   function in the builtin library.

\item
   At the end, there is documentation that describes where and how
   {\regina} differs from standard {\rexx}, as described in the two
   other sections. It also lists {\regina}s extensions to the builtin
   library.
\end{enumerate}

It is recommended that you read the first part on first on first
reading of this documentation, and that you use the second part as
reference. The third part is only relevant if you are going to use
{\regina}. 
\end{it}




\section{General Information}

This section is an introduction to the builtin functions. It describes
common behavior, parameter conventions, concepts and list possible
system-dependent parts. 


\subsection{The Syntax Format}

In the description of the builtin functions, the syntax of each one is
listed. For each of the syntax diagrams, the parts written in {\it
italic} font names the parameters. Terms enclosed in {\tt [}square
brackets{\tt ]} denote optional elements. And the {\tt courier} font
is used to denote that something should be written as is, and it is
also used to mark output from the computer. 

Note that in standard {\rexx} it is not really allowed to let the last
possible parameter be empty if all commas are included, although some
implementations allow it. In the following calls:
\begin{quote}
   {\tt say D2X( 61 )}\\
   {\tt say D2X( 61, 1 )}\\
   {\tt say D2X( 61, )}
\end{quote}
the two first return the string consisting of a single character {\tt
A}, while the last should return error. If the last argument of a
function call is omitted, you can not safely include the immediately
preceding comma.


\subsection{Precision and Normalization}

The built-in library uses its own internal precision for whole
numbers, which may be the range from -999999999 to +999999999. That is
probably far more than you will ever need in the builtin functions.
For most functions, neither parameters nor return values will be
effected by any setting of {\tt NUMERIC}. In the few cases where this
does not hold, it is explicitly stated in the description of the
function.

In general, only parameters that are required to be whole numbers are
used in the internal precision, while numbers not required to be whole
numbers are normalized according to the setting of {\tt NUMERIC}
before use.  But of course, if a parameter is a numeric expression,
that expression will be calculated and normalized under the settings
of {\tt NUMERIC} before it is given to the function as a parameter.




\subsection{Standard Parameter Names}

In the descriptions of the builtin functions, several generic names
are used for parameters, to indicate something about the type and use
of that parameter, e.g.~valid range. To avoid repeating the same
information for the majority of the functions, some common ``rules''
for the standard parameter names are stated here. These rules
implicitly apply for the rest of this chapter. 

Note that the following list does not try to classify any general
{\rexx} ``datatypes'', but provides a binding between the
sub-datatypes of strings and the methology used when naming
parameters.

\begin{itemize}
\item
   {\it Length} is a non-negative whole number within the internal
   precision of the builtin functions. Whether it denotes a length in
   characters or in words, depends on the context.

\item
   {\it String} can be any normal character string, including the
   nullstring. There are no further requirements for this parameter.
   Sometimes a string is called a ``packed string'' to explicitly show
   that it usually contains more than the normal printable characters.

\item
   {\it Option} is used in some of the functions to choose a
   particular action, e.g.~in {\tt DATE()} to set the format in which
   the date is returned. Everything except the first character will be
   ignored, and case does not matter. note that the string should
   concequently not have any leading space.

\item
   {\it Start} is a positive whole number, and denotes a start
   position in e.g.~a string. Whether it refers to characters or words
   depends on the context. The first position is always numbered {\tt
   1}, unless explicitly stated otherwise in the documentation.  Note
   that when return values denotes positions, the number {\tt 0} is
   generally used to denote a nonexistent position.

\item
   {\it Padchar} must be a string, exactly one character long.  That
   character is used for padding.

\item
   {\it Streamid} is a string that identifies a {\sc Rexx} stream. The
   actual contents and format of such a string is implementation
   dependant.

\item
   {\it Number} is any valid {\sc Rexx} number, and will be normalized
   according to the settings of {\tt NUMERIC} before it is used by the
   function.
\end{itemize}

If you see one of these names having a number appended, that is only
to separate several parameters of the same type, e.g.~{\it string1},
{\it string2}\/ etc. They still follow the rules listed above. There
are several parameters in the builtin functions that do not easily
fall into the categories above. These are given other names, and their
type and functionality will be described together with the functions
in which they occur.



\subsection{Error Messages}

There are several errors that might occur in the builtin functions.
Just one error message is only relevant for all the builtin functions,
that is number 40 ({\it Incorrect call to routine}). In fact, an
implementation of {\sc Rexx} can choose to use that for any problem it
encounters in the builtin functions.

Depending on the implementation, other error messages might be used as
well.  Error message number 26 ({\it Invalid whole number}) might be
used for any case where a parameter should have been a whole number,
or where a whole number is out of range.  It is implided that this
error message can be used in these situations, and it is not
explicitly mentioned in the description of the functions.

Other general error messages that might be used in the builtin
functions are error number 41 ({\it Bad arithmetic conversion}) for
any parameter that should have been a valid {\rexx} number. The error
message 15 ({\it Invalid binary or hexadecimal string}) might occur in
any of the converions routines that converts from binary or
hexadecimal format ({\tt B2X()}, {\tt X2B()}, {\tt X2C()}, {\tt
X2D()}). And of course the more general error messages like error
message 5 ({\it Machine resources exhausted}) can occur.

Generally, it is taken as granted that these error messages might
occur for any relavent builtin function, and this will not be restated
for each function. When other error messages than these are relevant,
it will be mentioned in the text.

In {\sc Rexx}, it is in general not an error to specify a start
position that is larger than the length of the string, or a length
that refers to parts of a string that is beyond the end of that
string. The meaning of such instances will depend on the context, and
are described for each function.



\subsection{Possible System Dependencies}

Some of the functions in the builtin library are more or less system
or implementation dependent. The functionality of these may vary, so
you should use defencive programming and be prepared for any
sideeffects that they might have.  These functions include:

\begin{itemize}
\item
   {\tt ADDRESS()} is dependant on your operating system and the
   implementation of {\sc Rexx}, since there is not standard for
   naming environments.

\item
   {\tt ARG()} at the main level (not in subroutines and functions) is
   dependant on how your implementation handles and parses the
   parameters it got from the operating system.

\item
   {\tt BITAND()}, {\tt BITOR()} and {\tt BITXOR()} are dependant on
   the character set of your machine. Seemingly identical parameters
   will in general return very different results on ASCII and EBCDIC
   machines. Results will be identical if the parameter was given to
   these functions as a binary or hexadecimal literal.

\item
   {\tt C2X()}, {\tt C2D()}, {\tt D2C()} and {\tt X2C()} will be
   effected by the character set of your computer since they convert
   to or from characters. Note that if {\tt C2X()} and {\tt C2D()} get
   their first parameter as a binary or hexadecimal literal, the
   result will be uneffected by the machine type. Also note that the
   functions {\tt B2X()}, {\tt X2B()}, {\tt X2D()} and {\tt D2X()} are
   not effected by the character set, since they do not use character
   representation.

\item
   {\tt CHARIN()}, {\tt CHAROUT()}, {\tt CHARS()}, {\tt LINEIN()},
   {\tt LINEOUT()}, {\tt LINES()} and {\tt STREAM()} are the interface
   to the filesystem. They might have system dependant pecularities in
   several ways. Firstly, the naming of streams is very dependant on
   the operating system. Secondly, the operation of stream is very
   dependent on both the operating system and the implementation. You
   can safely assume very little about how streams behave, so
   carefully read the documentation for your particular
   implementation.

\item
   {\tt CONDITION()} is dependant on the condition system, which in
   turn depends on such implementation dependant things as file I/O
   and execution of commands. Although the general operation of this
   function will be fairly equal among systems, the details may
   differ.

\item
   {\tt DATATYPE()} and {\tt TRANSLATE()} know how to recognize upper
   and lower case letters, and how to transform letters to upper case.
   If your {\rexx} implementation supports national character sets,
   the operation of these two functions will depend on the language
   choosen.

\item
   {\tt DATE()} has the options {\tt Month}, {\tt Weekday} and {\tt
   Normal}, which produce the name of the day or month in text.
   Depending on how your implementation handles national character
   sets, the result from these functions might use the correct
   spelling of the currently choosen language.

\item
   {\tt DELWORD()}, {\tt SUBWORD()}, {\tt WORD()}, {\tt WORDINDEX()},
   {\tt WORDLENGTH()}, {\tt WORDPOS()} and {\tt WORDS()} requires the
   concept of a ``word'', which is defined as a non-blank characters
   separated by blanks. However, the interpretation of what is a blank
   character depends upon the implementation. 

\item
   {\tt ERRORTEXT()} might have slightly different wordings, depending
   on the implementation, but the meaning and numbering should be the
   same. However, note that some implementations may have additional
   error messages, and some might not follow the standard numbering.

\item
   {\tt QUEUED()} refers to the system specific concept of a
   ``stack'', which is external to {\rexx}. The result of this
   function may therefore be dependant on how the stack is implemented
   on your system.

\item
   {\tt RANDOM()} will differ from machine to machine, since the
   algorithm is implementation dependant. If you set the seed, you can
   safely assume that the same interpreter under the same operating
   system and on the same hardware platform will return a
   reproduceable sequence.  But if you change to another interpreter,
   another machine or even just another version of the operating
   system, the same seed might not give the same pseudo-random
   sequence.

\item
   {\tt SOURCELINE()} has been changed between {\rexx} language level
   3.50 and 4.00. In 4.00 it can return {\tt 0} if the {\rexx}
   implementation finds it necessary, and any request for a particular
   line may get a nullstring as result. Before assuming that this
   function will return anything useful, consult the documentation.

\item
   {\tt TIME()} will differ somewhat on different machines, since it
   is dependent on the underlaying operating system to produce the
   timing information. In particular, the granularity and accuracy of
   this information may vary.

\item
   {\tt VALUE()} will be dependant on implementation and operating
   system if it is called with its third parameter specified. Consult
   the implementation specific documentation for more information
   about how each implementation handles this situation.

\item
   {\tt XRANGE()} will return a string, which contents will be
   dependent on the character set used by your computer. You can
   safely make very few assumptions about the visual representation,
   the length, or the character order of the string returned by this
   function.
\end{itemize}

As you can see, even {\rexx} interpreters that are within the standard
can differ quite a lot in the builtin library. Although the points
listed above seldom are any problem, you should never assume anything
about them before you have read the implementation specific
documentation.  Failure to do so will give you surprises sooner or
later.

And, by the way, many implementations (probably the majority)
do not follow the standard completely. So, in fact, you should never
assume anything at all. Sorry ...



\subsection{Blanks vs.~Spaces}

Note that the description differs between ``blanks'' and the {\sc
space} character. A blank is any character that might be used as
``whitespace'' to separate text into groups of characters. The {\sc
space} character is only one of several possible blanks. When this
text says ``blank'' it means any one from a set of characters that are
used to separate visual characters into words. When this text says
{\sc space}, it means one particular blank, that which is generally
binded to the spacebar on a normal computer keyboard.

All implementation can be trusted to treat the {\sc space} character
as blank.  Additional characters that might be interpreted as blanks
are {\sc tab} (horizontal tabulator), {\sc ff} (formfeed), {\sc vt}
(vertical tabulator), {\sc nl} (newline) and {\sc cr} (carriage
return). The interpretation of what is blank will vary between
machines, operating systems and interpreters. If you are using support
for national character sets, it will even depend on the language
selected. So be sure to check the documentation before you assume
anything about blank characters.

Some implementations use only one blank character, and perceives
the set of blank characters as equivalent to the {\sc space}
character. This will depend on the implementation, the character set,
the customs of the operating system and various other reasons. 




\section{{\sc Rexx} Standard Builtin Functions}

Below follows an in depth description of all the functions in the
library of builtin functions. Note that only the standard {\rexx}
functions is included. The extended functions available in some
implementations are not described here. 


\heading{ABBREV({\it long},{\it short}[,{\it length}])}{\rexxfunc}

Returns {\tt 1} if the string {\it short} is strictly equal to the
initial first part of the string {\it long}, and returns {\tt 0}
otherwise.  The minimum length which {\it short} must have, can be
specified as {\it length}.  If {\it length} is unspecified, no minimum
restrictions for the length of {\it short} applies, and thus the
nullstring is an abbreviation of any string.

Note that this function is case sensitive, and that leading and
trailing spaces are not stripped off before the two strings are
compared. 

\begin{quote}
\begin{tabular}{lll}
   {\tt ABBREV( 'Foobar', 'Foo' )}   & $\rightarrow$ & {\tt 1}\\
   {\tt ABBREV( 'Foobar', 'Foo', 4)} & $\rightarrow$ & 
                   {\tt 0 ~/* {\rm\it Too short} */}\\
   {\tt ABBREV( 'Foobar', 'foo' )}   & $\rightarrow$ & 
               {\tt 0 ~/* {\rm\it Different case} */} 
\end{tabular}
\end{quote}



\heading{ABS({\it number})}{\rexxfunc}

Returns the absolute value of the {\it number}, which can be any valid
{\rexx} number. Note that the result will be normalized according to
the current setting of {\tt NUMERIC}.

\begin{quote}
\begin{tabular}{lll}
   {\tt ABS( -42 )} & $\rightarrow$ & {\tt 42}\\
   {\tt ABS( 100 )} & $\rightarrow$ & {\tt 100}
\end{tabular}
\end{quote}


\heading{ADDRESS()}{\rexxfunc}

Returns the current default environment to which commands are sent.
The value is set with the {\tt ADDRESS} clause, for more information,
see documentation on that clause.

\begin{quote}
\begin{tabular}{lll}
   {\tt ADDRESS()} & $\rightarrow$ & {\tt UNIX ~/* {\rm\it Maybe} */}
\end{tabular}
\end{quote}



\heading{ARG([{\it argno}[,{\it option}]])}{\rexxfunc}

Returns information about the arguments of the current procedure
level. For subroutines and functions it will refer to the arguments
with which they were called. For the ``main'' program it will refer to
the arguments used when the {\sc Rexx} interpreter was called. 

Note that in under some operating systems, {\rexx} scripts are run by
starting a the rexx interpreter as a program, giving it the name of
the script to be executed as parameter. Then then {\rexx} interpreter
might process the commandline and ``eat'' some or all of the arguments
and options.  Therefore, the result of this function at the main level
is implementation dependant.  The parts of the command line which are
not available to the {\rexx} script might for instance be the options
and arguments meaningful only to the interpreter itself.  

Also note that how the interpreter on the main level divides the
parameter line into individual arguments, is implementation dependent.
The standard seems to define that the main procedure level can only
get one parameter string, but don't count on it. 

For more information on how the interpreter processes arguments when
called from the operating system, see the documentation on how to run
a {\rexx} script. 

When called without any parameters, {\tt ARG()} will return the number
of comma-delimited arguments. Unspecified (omitted) arguments at the
end of the call are not counted. Note the difference between using
comma and using space to separate strings.  Only comma-separated
arguments will be interpreted by {\rexx} as different arguments.
Space-separated strings are interpreted as different parts of the same
argument.

{\it Argno} must be a positive whole number. If only {\it argno} is
specified, the argument specified will be returned. The first argument
is numbered 1. If {\it argno} refers to an unspecified argument
(either omitted or {\it argno} is greater than the number of
arguments), a nullstring is returned.

If {\it option} is also specified, the return value will be {\tt 1} or
{\tt 0}, depending on the value of {\it option} and on whether the
numbered parameter was specified or not. Option can be:
\begin{itemize}
\item[{\tt O}]
   (Omitted) Returns {\tt 1} if the numbered argument was omitted or
   unspecified. Otherwise, {\tt 0} is returned.

\item[{\tt E}]
   (Existing) Returns {\tt 1} if the numbered argument was specified,
   and {\tt 0} otherwise.
\end{itemize}

If called as: {\tt CALL FUNCTION 'This' 'is', 'a',, 'test',,}

\begin{quote}
\begin{tabular}{lll}
   {\tt ARG()} & $\rightarrow$ & 
                          {\tt 4 ~/* {\rm\it Last parameter ommitted} */}\\
   {\tt ARG(1)} & $\rightarrow$ & {\tt 'This is'}\\
   {\tt ARG(2)} & $\rightarrow$ & {\tt 'a'}\\
   {\tt ARG(3)} & $\rightarrow$ & {\tt ''}\\
   {\tt ARG(9)} & $\rightarrow$ & 
                      {\tt '' ~/* {\rm\it Ninth parameter nonexisting} */}\\
   {\tt ARG(2,'E')} & $\rightarrow$ & {\tt 1}\\
   {\tt ARG(2,'O')} & $\rightarrow$ & {\tt 0}\\
   {\tt ARG(3,'E')} & $\rightarrow$ & 
                      {\tt 0 ~/* {\rm\it Third parameter ommitted} */}\\
   {\tt ARG(9,'O')} & $\rightarrow$ & {\tt 1}
\end{tabular}
\end{quote}



\heading{B2X({\it binstring})}{\rexxfuncs}

Takes a parameter which is interpreted as a binary string, and returns
a hexadecimal string which represent the same infomation. {\it
Binstring} can only contain the binary digits {\tt 0} and {\tt 1}.  To
increase readability, blanks may be included in {\it binstring} to
group the digits into groups. Each such group must have a multiple of
four binary digits, except from the first group. If the number of
binary digits in the first group is not a multiple of four, that group
is padded at the left with up to three leading zeros, to make it a
multiple of four. Blanks can only occur between binary digits, not as
leading or trailing characters.

Each group of four binary digits is translated into on hexadecimal
digit in the output string. There will be no extra blanks in the
result, and the upper six hexadecimal digits are in upper case.

\begin{quote}
\begin{tabular}{lll}
   {\tt B2X('0010 01011100 0011')} & $\rightarrow$ & {\tt '26C3'}\\
   {\tt B2X('10 0101 11111111')} & $\rightarrow$ & {\tt '26FF'}\\
   {\tt B2X('0100100 0011')} & $\rightarrow$ & {\tt '243'}\\
\end{tabular}
\end{quote}




\heading{BITAND({\it string1}[,[{\it string2}][,{\it padchar}]])}{\rexxfunc}

Returns the result from bytewise applying the operator AND to the
characters in the two strings {\it string1} and {\it string2}. Note
that this is not the logical AND operation, but the bitwise AND
operation. {\it String2} defaults to a nullstring. The two strings are
left-justified; the first characters in both strings will be AND'ed,
then the second characters and so forth.

The behavior of this function when the two strings do not have equal
length is defined by the {\it padchar} character. If it is udefined,
the remaining part of the longer string is appended to the result
after all characters in the shorter srting have been processed. If
{\it padchar} is defined, each char in the remaining part of the
longer string is logically AND'ed with the {\it padchar} (or rather,
the shorter string is padded on the right length, using {\it
padchar}).

When using this function on character strings, e.g.~to uppercase or
lowercase a string, the result will be dependant on the character set
used. To lowercase a string in EBCDIC, use {\tt BITAND()} with a {\it
padchar} value of {\tt 'bf'x}. To do the same in ASCII, use {\tt
BITOR()} with a {\it padchar} value of {\tt '20'x}.

\begin{quote}
\begin{tabular}{lll}
   {\tt BITAND('123456'x, '3456'x)} & $\rightarrow$ & {\tt '101456'x}\\
   {\tt BITAND('foobar',, 'df'x)} & $\rightarrow$ & {\tt 'FOOBAR'  
                                              ~/* {\rm\it For ASCII} */}\\
   {\tt BITAND('123456'x, '3456'x, 'f0'x)} & $\rightarrow$ & {\tt '101450'x}
\end{tabular}
\end{quote}




\heading{BITOR({\it string1}[,[{\it string2}][,{\it padchar}]])}{\rexxfunc}

Works like {\tt BITAND()}, except that the logical function OR is used
instead of AND. For more information see {\tt BITAND()}.

\begin{quote}
\begin{tabular}{lll}
   {\tt BITOR('123456'x, '3456'x)} & $\rightarrow$ & {\tt '367656'x}\\
   {\tt BITOR('FOOBAR',, '20'x)} & $\rightarrow$ & {\tt 'foobar'  
                                               ~/* {\rm\it For ASCII} */}\\
   {\tt BITOR('123456'x, '3456'x, 'f0'x)} & $\rightarrow$ & {\tt '3676F6'x}
\end{tabular}
\end{quote}



\heading{BITXOR({\it string1}[,[{\it string2}][,{\it padchar}]])}{\rexxfunc}

Works like {\tt BITAND()}, except that the logical function XOR
(exclusive OR) is used instead of AND. For more information see {\tt
BITAND()}.

\begin{quote}
\begin{tabular}{lll}
   {\tt BITXOR('123456'x, '3456'x)} & $\rightarrow$ & {\tt '266256'x}\\
   {\tt BITXOR('FooBar',, '20'x)} & $\rightarrow$ & {\tt 'fOObAR'  
                                               ~/* {\rm\it For ASCII} */}\\
   {\tt BITXOR('123456'x, '3456'x, 'f0'x)} & $\rightarrow$ & {\tt '2662A6'x}
\end{tabular}
\end{quote}



\heading{C2D({\it string}[,{\it length}])}{\rexxfunc}

Returns an whole number, which is the decimal representation of the
packed string {\it
string}, interpreted as a binary number. If {\it length} (which must
be a non-negative whole number) is specified, it denotes the number of
characters in {\it string} to be converted, and {\it string} is
interpreted as a two's complement representation of a binary number,
consisting of the length rightmost characters in {\it string}. If {\it
length} is not specified, {\it string} is interpreted as an unsigned
number. 

If {\it length} is larger than the length of {\it string}, {\it
string} is sign-extended on the left.  I.e.~if the most significant bit of the
leftmost char of {\it string} is set, {\it string} is padded with {\tt
'ff'x} chars at the left side. If the bit is not set, {\tt '00'x}
chars are used for padding.

If {\it length} is too short, only the {\it length} rightmost
characters in {\it string} are considered. Note that this will not
only in general change the value of the number, but it might even
change the sign.

Note that this function is very dependant on the character set that
your computer is using. 

If it is not possible to express the final result as a whole number under
the current settings of {\tt NUMERIC DIGITS}, an error is reported.
The number to be returned will not be stored in the internal
representation of the builtin library, so size restrictions on whole
numbers that generally applies for builtin functions, do not apply in
this case.

\begin{quote}
\begin{tabular}{lll}
   {\tt C2D('foo')} & $\rightarrow$ & {\tt '6713199' 
                                      ~/* {\rm\it For ASCII machines} */}\\
   {\tt C2D('103'x)} & $\rightarrow$ & {\tt '259'}\\
   {\tt C2D('103'x,1)} & $\rightarrow$ & {\tt '3'}\\
   {\tt C2D('103'x,2)} & $\rightarrow$ & {\tt '259'}\\
   {\tt C2D('0103'x,3)} & $\rightarrow$ & {\tt '259'}\\
   {\tt C2D('ffff'x,2)} & $\rightarrow$ & {\tt '-1'}\\
   {\tt C2D('ffff'x)} & $\rightarrow$ & {\tt '65535'}\\
   {\tt C2D('ffff'x,3)} & $\rightarrow$ & {\tt '65535'}\\
   {\tt C2D('fff9'x,2)} & $\rightarrow$ & {\tt '-6'}\\
   {\tt C2D('ff80'x,2)} & $\rightarrow$ & {\tt '-128'}
\end{tabular}
\end{quote}




\heading{C2X({\it string})}{\rexxfunc}

Returns a string of hexadecimal digits that represents the character
string {\it string}. Converting is done bytewise, the six highest
hexadecimal digits are in uppercase, and there are no blank characters
in the result Leading zeros are not stripped off in the result. Note
that the behavior of this function is dependant on the character set
that your computer is running (e.g.~ASCII or EBCDIC).

\begin{quote}
\begin{tabular}{lll}
   {\tt C2X('ffff'x)} & $\rightarrow$ & {\tt 'FFFF'}\\
   {\tt C2X('Abc')} & $\rightarrow$ & {\tt '416263' 
                                     ~/* {\rm\it For ASCII Machines} */}\\
   {\tt C2X('1234'x)} & $\rightarrow$ & {\tt '1234'}\\
   {\tt C2X('011 0011 1101'b)} & $\rightarrow$ & {\tt '033D'}
\end{tabular}
\end{quote}




\heading{CENTER({\it string},{\it length}[,{\it 
                                          padchar}])}{\rexxfunc}\vspace{-5mm}
\heading{CENTRE({\it string},{\it length}[,{\it padchar}])}{\rexxfunc}

This function has two names, to support both American and British
spelling. It will center {\it string} in a string total of length {\it
length} characters. If {\it length} (which must be a non-negative
wholenumber) is greater than the length of {\it string}, {\it string}
is padded with {\it padchar} or {\sc space} if {\it padchar} is
unspecified. If {\it length} is smaller than the length of {\it
string} character will be removed. 

If possible, both ends of {\it string} receives (or loses) the same
number of characters. If an odd number of characters are to be added
(or removed), one character more is added to (or removed from) the
right end than the left end of {\it string}.


\begin{quote}
\begin{tabular}{lll}
   {\tt CENTER('Foobar',10)} & $\rightarrow$ & {\tt ' ~Foobar~ '}\\
   {\tt CENTER('Foobar',11)} & $\rightarrow$ & {\tt ' ~Foobar~ ~'}\\
   {\tt CENTRE('Foobar',3)} & $\rightarrow$ & {\tt 'oob'}\\
   {\tt CENTER('Foobar',4)} & $\rightarrow$ & {\tt 'ooba'}\\
   {\tt CENTER('Foobar',10,'*')} & $\rightarrow$ & {\tt '**Foobar**'}
\end{tabular}
\end{quote}




\heading{CHARIN([{\it streamid}][,[{\it start}][,{\it length}]])}{\rexxfunc}

This function will in general read characters from a stream, and
return a string containing the characters read. The {\it streamid}
parameter names a particular stream to read from. If it is
unspecified, the default input stream is used. 

The {\it start} parameter specifies a character in the stream, on
which to start reading. Before anything is read, the current read
position is set to that character, and it will be the first character
read. If {\it start} is unspecified, no repositioning will be done.
Independant of any conventions of the operating system, the first
character in a stream is always numbered 1. Note that transient
streams do not allow repositioning, and an error is reported if the
{\it start} parameter is specified for a transient stream. 

The {\it length} parameter specifies the number of characters to read.
If the reading did work, the return string will be of length {\it
length}. There are no other ways to how many characters were read than
checking the length of the return value. After the read, the current
read position is moved forward as many characters as was read. If {\it
length} is unspecified, it defaults to {\tt 1}. If {\it length} is
{\tt 0}, nothing is read, but the file might still be reposisioned if
{\it start} was specified. 

Note that this function read the stream raw. Some operating systems
use special characters to differ between separate lines in text files.
On these systems these special characters will be returned as well.
Therefore, never assume that this function will behave identical for
text streams on different systems.

What happens when an error occurs or the End-Of-File (EOF) is seen
during reading, is implementation dependant. The implementation may
choose to set the {\tt NOTREADY} condition (does not exist in {\rexx}
language level 3.50). For more information, se chapter on stream I/O.

(Assuming that the file ``{\tt /tmp/file}'' contains the first line:
``{\tt This is the first line}''):

\begin{quote}
\begin{tabular}{lll}
   {\tt CHARIN()} & $\rightarrow$ & {\tt 'F' ~/* {\rm\it Maybe} */}\\
   {\tt CHARIN(,,6)} & $\rightarrow$ & {\tt 'Foobar' ~/* {\rm\it Maybe} */}\\
   {\tt CHARIN('/tmp/file',,6)} & $\rightarrow$ & {\tt 'This i'}\\
   {\tt CHARIN('/tmp/file',4,6)} & $\rightarrow$ & {\tt 's is t'}
\end{tabular}
\end{quote}




\heading{CHAROUT([{\it streamid}][,[{\it string}][,{\it start}]])}{\rexxfunc}

In general this function will write {\it string} to a {\it streamid}.
If {\it streamid} is not specified the default output stream will be
used. 

If {\it start} is specified, the current write position will be set to
the {\it start}\/th character in {\it streamid}, before any writing is
done. Note that the current write position ca not be set for transient
streams, and attempts to do so will report an error. Independant of
any conventions that the operating system might have, the first
character in the stream is numbered {\tt 1}. If {\it start} is not
specified, the current write position will not be changed before
writing.

If {\it string} is omitted, nothing is written, and the effect is to
set the current write position if {\it start} is specified. If neither
{\it string} nor {\it start} is specified, the implementation can
really do whatever it likes, and many implementations use this
operation to close the file, or flush any changes. Check
implementation specific documentation for more info.

The return value is the number of characters in {\it string} that was
not successfully written, so {\tt 0} denotes a succesful write. Note
that in many {\rexx} implementations there is no need to open a
stream; it will be implicitly opened when it is first used in a read
or write operation. 

(Assuming the file referred to by {\tt outdata} was empty, it will
contain the string {\tt FoobWow} afterwards. Note that there might
will not be an End-Of-Line marker after this string, it depends on the
implementation.)

\begin{quote}
\begin{tabular}{lll}
   {\tt CHAROUT(, 'Foobar')} & $\rightarrow$ & {\tt '0'}\\
   {\tt CHAROUT(outdata, 'Foobar')} & $\rightarrow$ & {\tt '0'}\\
   {\tt CHAROUT(outdata, 'Wow', 5)} & $\rightarrow$ & {\tt '0'}\\
\end{tabular}
\end{quote}





\heading{CHARS([{\it streamid}])}{\rexxfunc}

Returns the number of characters left in the named {\it streamid}, or
the default input stream if {\it streamid} is unspecified. For
transient streams this will always be either {\tt 1} if more
characters are available, or {\tt 0} if the End-Of-File condition has
been met. For persistent streams the number of remaining bytes in the
file will be possible to calculate and the true number of remaining
bytes will be returned.

However, on some systems, it is difficult to calculate the number of
characters left in a persistent stream; the requirements to {\tt
CHARS()} has therefore been relaxed, so it can return {\tt 1} instead
of any number other than {\tt 0}. If it returns {\tt 1}, you can
therefore not assume anything more than that there is at least one
more character left in the input stream.

\begin{quote}
\begin{tabular}{lll}
   {\tt CHARS()} & $\rightarrow$ & {\tt '1' 
                          ~/* more data on def. input stream */}\\
   {\tt CHARS()} & $\rightarrow$ & {\tt '0'
                          ~/* EOF for def. input stream */}\\
   {\tt CHARS('outdata')} & $\rightarrow$ & {\tt '94' ~/* {\rm\it maybe} */}\\
\end{tabular}
\end{quote}





\heading{COMPARE({\it string1},{\it string2}[,{\it padchar}])}{\rexxfunc}

This function will compare {\it string1} to {\it string2}, and return
a whole number which will be 0 if they are equal, otherwise the
position of the first character at which the two strings differ is
returned. The comparisation is case-sensitive, and leading and
trailing space do matter.

If the strings are of unequal length, the shorter string will be
padded at the right hand end with the {\it padchar} character to the
length of the longer string before the comparation. If a {\it padchar}
is not specified, {\sc space} is used.

\begin{quote}
\begin{tabular}{lll}
   {\tt COMPARE('FooBar', 'Foobar')} & $\rightarrow$ & {\tt '4'}\\
   {\tt COMPARE('Foobar', 'Foobar')} & $\rightarrow$ & {\tt '0'}\\
   {\tt COMPARE('Foobarrr', 'Fooba')} & $\rightarrow$ & {\tt '6'}\\
   {\tt COMPARE('Foobarrr', 'Fooba', 'r' )} & $\rightarrow$ & {\tt '0'}
\end{tabular}
\end{quote}




\heading{CONDITION([{\it option}])}{\rexxfunc}

Returns information about the current trapped condition. A condition
becomes the current trapped condition when a condition handler is
called (by {\tt CALL} or {\tt SIGNAL}) to handle the condition.
The parameter {\it option} specifies what sort of information to
return:

\begin{itemize}
\item[{\tt C}]
   (Condition) The name of the current trapped condition is return,
   this will be one of the condition named legal to {\tt SIGNAL ON},
   like {\tt SYNTAX}, {\tt HALT}, {\tt NOVALUE}, {\tt NOTREADY}, {\tt
   ERROR} or {\tt FAILURE}.

\item[{\tt D}]
   (Description) A text describing the reason for the condition. What
   to put into this variable is implementation and system dependant.

\item[{\tt I}]
   (Instruction) Returns either {\tt CALL} or {\tt SIGNAL}, depending
   on which method was current when the condition was trapped. 

\item[{\tt S}]
   (State) The current state of the current trapped condition. This
   can be one of {\tt ON}, {\tt OFF} or {\tt DELAY}. Note that this
   option reflect the current state, which may change, not the state
   at the time when the condition was trapped. 
\end{itemize}

For more information on conditions, consult the chapter
\ref{ch:conditions}. Note that condition may in several ways be
dependant on the implementation and system, so read system and
implementation dependant information too.


\heading{COPIES({\it string},{\it copies})}{\rexxfunc}

Returns a string with {\it copies} concatenated copies of {\it
string}. {\it Copies} must be a non-negative whole number. No extra space
is added between the copies.

\begin{quote}
\begin{tabular}{lll}
   {\tt COPIES('Foo', 3)} & $\rightarrow$ & {\tt 'FooFooFoo'}\\
   {\tt COPIES('*', 16)} & $\rightarrow$ & {\tt '****************'}\\
   {\tt COPIES('Bar ', 2)} & $\rightarrow$ & {\tt 'Bar Bar '}\\
   {\tt COPIES('', 10000)} & $\rightarrow$ & {\tt ''}
\end{tabular}
\end{quote}




\heading{DATATYPE({\it string}[,{\it option}])}{\rexxfunc}

With only one parameter, this function identifies the
``datatype'' of {\it string}. The value returned will be ``{\tt
NUM}'' if {\it string} is a valid {\sc Rexx} number. Otherwise, ``{\tt
CHAR}'' is returned.  Note that the interpretation of whether {\it
string} is a valid number will depend on the current setting of {\tt
NUMERIC}.

If {\it option} is specified too, it will check if {\it string} is of
a particular datatype, and return either ``{\tt 1}'' or ``{\tt 0}''
depending on whether {\it string} is or is not, respectively, of the
specified datatype. The possible values of {\it option} are:
\begin{itemize}
\item[{\tt A}]
   (Alphanumeric) Consisting of only alphabetic characters (in upper,
   lower or mixed case) and decimal digits. 

\item[{\tt B}]
   (Binary) Consisting of only the two binary digits {\tt 0} and {\tt
   1}. Note that blanks are not allowed within {\it string}, as would
   have allowed been within a binary string.

\item[{\tt L}]
   (Lower) Consisting of only alphabetic characters in lower case.

\item[{\tt M}]
   (Mixed) Consisting of only alphabetic characters, but the case does
   not matter (i.e.~upper, lower or mixed.)

\item[{\tt N}]
   (Numeric) If {\it string} is a valid {\sc Rexx} number, i.e.~{\tt
   DATATYPE({\it string})} would return {\tt NUM}.

\item[{\tt S}]
   (Symbolic) Consists of characters that are legal in {\sc Rexx} symbols.
   Note that this test will pass several strings that are not legal
   symbols. The characters includes plus, minus and the decimal point.

\item[{\tt U}]
   (Upper) Consists of only upper case alphabetic characters.

\item[{\tt W}]
   (Whole) If {\it string} is a valid {\sc Rexx} whole number under the
   current setting of {\tt NUMERIC}. Note that {\tt 13.0} is a whole
   number since the decimal part is zero, while {\tt 13E+1} is not a
   whole number, since it must be interpreted as 130 plus/minus 5.

\item[{\tt X}]
   (Hexadecimal) Consists of only hexadecimal digits, i.e.~the decimal
   digits 0-9 and the alphabetic characters A-F in either case (or
   mixed.) Note that blanks are not allowed within {\it string}, as it
   would have been within a hexadecimal string. 
\end{itemize}

If you want to check whether a string is suitable as a variable name,
you should consider using the {\tt SYMBOL()} function instead, since
the {\tt Symbolic} option only verifies which characters {\it string}
contains, not the order. You should also take care to watch out for
lower case alphabetic characters, which are allowed in the tail of a
compound symbol, but not in a simple or stem symbol or in the head of
compound symbol.

Also note that the behavior of the options {\tt A}, {\tt L}, {\tt M}
and {\tt U} might depend on the setting of language, if you
are using an interpreter that supports national character sets.

\begin{quote}
\begin{tabular}{lll}
   {\tt DATATYPE(' - 1.35E-5 ')} & $\rightarrow$ & {\tt 'NUM'}\\
   {\tt DATATYPE('1E999999999')} & $\rightarrow$ & {\tt 'CHAR'}\\
   {\tt DATATYPE('1E9999999999')} & $\rightarrow$ & {\tt 'CHAR'}\\
   {\tt DATATYPE('!@\#\&\#\$(\&*\%`')} & $\rightarrow$ & {\tt 'CHAR'}\\
   {\tt DATATYPE('FooBar', 'A')} & $\rightarrow$ & {\tt '1'}\\
   {\tt DATATYPE('Foo Bar', 'A')} & $\rightarrow$ & {\tt '0'}\\
   {\tt DATATYPE('010010111101', 'B')} & $\rightarrow$ & {\tt '1'}\\
   {\tt DATATYPE('0100 1011 1101', 'B')} & $\rightarrow$ & {\tt '0'}\\
   {\tt DATATYPE('foobar', 'L')} & $\rightarrow$ & {\tt '1'}\\
   {\tt DATATYPE('FooBar', 'M')} & $\rightarrow$ & {\tt '1'}\\
   {\tt DATATYPE(' -34E3 ', 'N')} & $\rightarrow$ & {\tt '1'}\\
   {\tt DATATYPE('A\_SYMBOL!?!', 'S')} & $\rightarrow$ & {\tt '1'}\\
   {\tt DATATYPE('1.23.39E+4.5', 'S')} & $\rightarrow$ & {\tt '1'}\\
   {\tt DATATYPE('Foo bar', 'S')} & $\rightarrow$ & {\tt '0'}\\
   {\tt DATATYPE('FOOBAR', 'U')} & $\rightarrow$ & {\tt '1'}\\
   {\tt DATATYPE('123deadbeef', 'X')} & $\rightarrow$ & {\tt '1'}
\end{tabular}
\end{quote}




\heading{DATE([{\it option}])}{\rexxfunc}

This function returns information relating to the current date. If
the {\it option} character is specified, it will set the format of the
return string. The default value for {\it option} is ``{\tt N}''. 
Possible options are:
\begin{itemize}
\item[{\tt B}] 
   (Base) The number of days from January 1st 0001 until yesterday
   inclusive, as a whole number. This function uses the Gregorian
   calendar extended backwards.

\item[{\tt C}]
   (Century) The number of days in this century from January 1st 
   {\tt --}00 until today, inclusive. The return value will be a
   positive integer. 

\item[{\tt D}]
   (Days) The number of days in this year from January 1st until today,
   inclusive. The return value will be a positive integer.

\item[{\tt E}]
   (European) The date in European format, i.e.~``{\tt dd/mm/yy}''. If any
   of the numbers is single digit, it will have a leading zero.

\item[{\tt M}]
   (Month) The unabbreviated name of the current month, in English.

\item[{\tt N}]
   (Normal) Return the date with the name of the month abbreviated to
   three letters, with only the first letter in upper case. The format
   will be ``{\tt dd Mmm yyyy}'', where {\tt Mmm} is the month
   abbreviation and {\tt dd} is the day of the month, without leading
   zeros.

\item[{\tt O}]
   (Ordered) Returns the date in the ordered format, which is ``{\tt
   yy/mm/dd}''.

\item[{\tt S}]
   (Standard) Returns the date according the format specified by
   International Standards Organization Recommendation ISO/R 2014-1971
   (E). The format will be ``{\tt yyyymmdd}'', and each part is padded
   with leading zero where appropriate.

\item[{\tt U}]
   (USA) Returns the date in the format that is normally used in USA,
   i.e.~``{\tt mm/dd/yy}'', and each part is padded with leading
   zero where appropriate.

\item[{\tt W}]
   (Weekday) Returns the English unabbreviated name of the 
   current weekday for today. The first letter of the result is
   in upper case, the rest is in lower case.
\end{itemize}

Note that the ``{\tt C}'' option is present in {\sc Rexx} language level
3.50, but was removed in level 4.00. The new ``{\tt B}'' option should
be used instead. When porting code that use the ``{\tt C}'' option
to an interpreter that only have the ``{\tt B}'' option, you will
can use the conversion that January 1st 1900 is day 693595 in the
Gregorian calendar.

Note that none of the formats in which {\tt DATE()} return its answer
are effected by the settings of {\tt NUMERIC}. Also note that if there
are more than one call to {\tt DATE()} (and {\tt TIME()}) in a single
clause of {\sc Rexx} code, all of them will use the same basis data for
calculating the date (and time).

If the {\sc Rexx} interpreter contains national support, some of these
options may return different output for the names of months and
weekdays.

Assuming that today is January 6th 1992:

\begin{quote}
\begin{tabular}{lll}
   {\tt DATE('B')} & $\rightarrow$ & {\tt '727203'}\\
   {\tt DATE('C')} & $\rightarrow$ & {\tt '33609'}\\
   {\tt DATE('D')} & $\rightarrow$ & {\tt '6'}\\
   {\tt DATE('E')} & $\rightarrow$ & {\tt '06/01/92'}\\
   {\tt DATE('M')} & $\rightarrow$ & {\tt 'January'}\\
   {\tt DATE('N')} & $\rightarrow$ & {\tt '6 Jan 1992'}\\
   {\tt DATE('O')} & $\rightarrow$ & {\tt '92/01/06'}\\
   {\tt DATE('S')} & $\rightarrow$ & {\tt '19920106'}\\
   {\tt DATE('U')} & $\rightarrow$ & {\tt '01/06/92'}\\
   {\tt DATE('W')} & $\rightarrow$ & {\tt 'Monday'}\\
\end{tabular}
\end{quote}





\heading{DELSTR({\it string},{\it start}[,{\it length}])}{\rexxfunc}

Returns {\it string}, after the substring of length {\it length}
starting at position {\it start} has been removed. The default value
for {\it length} is the rest of the string. {\it Start} must be a
positive whole number, while {\it length} must be a non-negative whole
number.  It is not an error if {\it start} or {\it length} (or a
combination of them) refers to more characters than {\it string} holds

\begin{quote}
\begin{tabular}{lll}
   {\tt DELSTR('Foobar', 3)} & $\rightarrow$ & {\tt 'Foo'}\\
   {\tt DELSTR('Foobar', 3, 2)} & $\rightarrow$ & {\tt 'Foor'}\\
   {\tt DELSTR('Foobar', 3, 4)} & $\rightarrow$ & {\tt 'Foo'}\\
   {\tt DELSTR('Foobar', 7)} & $\rightarrow$ & {\tt 'Foobar'}\\
\end{tabular}
\end{quote}




\heading{DELWORD({\it string},{\it start}[,{\it length}])}{\rexxfunc}

Removes {\it length} words and all blanks between them, from {\it
string}, starting at word number {\it start}. The default value for
{\it length} is the rest of the string.  All concequitive spaces
immediately after the last deleted word, but no spaces
before the first deleted word is removed. Nothing is removed if {\it
length} is zero. 

The valid range of {\it start} is the positive whole numbers; the
first word in {\it string} is numbered {\tt 1}. The valid range of
{\it length} is the non-negative integers. It is not an error if {\it
start} or {\it length} (or a combination of them) refers to more words
than {\it string} holds.

\begin{quote}
\begin{tabular}{lll}
   {\tt DELWORD('This is a test', 3)} & $\rightarrow$ & 
                         {\tt 'This is '}\\
   {\tt DELWORD('This is a test', 2, 1)} & $\rightarrow$ & 
                                             {\tt 'This a test'}\\
   {\tt DELWORD('This is a test', 2, 5)} & $\rightarrow$ & {\tt 'This'}\\
   {\tt DELWORD('This is a test', 1, 3)} & $\rightarrow$ & 
                        {\tt 'test' ~/* {\rm\it No leading space} */}
\end{tabular}
\end{quote}



\heading{DIGITS()}{\rexxfunc}

Returns the current precision of arithmetic operations. This value is
set using the {\tt NUMERIC} statement. For more information, refer to
the documentation on {\tt NUMERIC}.

\begin{quote}
\begin{tabular}{lll}
   {\tt DIGITS()} & $\rightarrow$ & {\tt '9' ~/* {\rm\it Maybe} */}\\
\end{tabular}
\end{quote}




\heading{D2C({\it integer}[,{\it length}])}{\rexxfunc}

Returns a (packed) string, that is the character representation of {\it
integer}, which must be a whole number, and is governed by the
settings of {\tt NUMERIC}, not of the internal precision of the
builtin functions. If {\it length} is
specified the string returned will be {\it length} bytes long, with
sign extension. If {\it length} (which must be a non-negative whole
number) is not large enough to hold the result, an error is reported.

If {\it length} is not specified, {\it integer} will be interpreted as
an unsigned number, and the result will have no leading {\sc nul}
characters.  If {\it integer} is negative, it will be interpreted as a
two's complement, and {\it length} must be specified.

\begin{quote}
\begin{tabular}{lll}
   {\tt D2C(0)} & $\rightarrow$ & {\tt ''}\\
   {\tt D2C(127)} & $\rightarrow$ & {\tt '7F'x}\\
   {\tt D2C(128)} & $\rightarrow$ & {\tt '80'x}\\
   {\tt D2C(128, 3)} & $\rightarrow$ & {\tt '000080'x}\\
   {\tt D2C(-128)} & $\rightarrow$ & {\tt '80'x}\\
   {\tt D2C(-10, 3)} & $\rightarrow$ & {\tt 'fffff5'x}\\
\end{tabular}
\end{quote}





\heading{D2X({\it integer}[,{\it length}])}{\rexxfunc}

Returns a hexadecimal number that is the hexadecimal representation of
{\it integer}. {\it Integer} must be a whole number under the current
settings of {\tt NUMERIC}, it is not effected by the precision of the
builtin functions. 

If {\it length} is not specified, then {\it integer} must be non-negative,
and the result will be stripped of any leading zeros. 

If {\it length} is specified, then the resulting string will have that
length. If necessary, it will be signextended on the left side to make
it the right length. If {\it length} is not large enough to hold {\it
integer}, an error is reported. 

\begin{quote}
\begin{tabular}{lll}
   {\tt D2X(0)} & $\rightarrow$ & {\tt '0'}\\
   {\tt D2X(127)} & $\rightarrow$ & {\tt '7F'}\\
   {\tt D2X(128)} & $\rightarrow$ & {\tt '80'}\\
   {\tt D2X(128, 5)} & $\rightarrow$ & {\tt '00080'x}\\
   {\tt D2X(-128)} & $\rightarrow$ & {\tt '80'x}\\
   {\tt D2X(-10, 5)} & $\rightarrow$ & {\tt 'ffff5'x}\\
\end{tabular}
\end{quote}




\heading{ERRORTEXT({\it errno})}{\rexxfunc}

Returns the {\sc Rexx} error message associated with error number {\it errno}.
If the error message is not defined, a nullstring is returned.

The error messages in {\sc Rexx} might be slightly different between
the various implementations.  The standard says that {\it errno} must
be in the range 0-99, but in some implementations it might be within a
less restricted range which gives room for system specific messages.
You should in general not assume that the wordings and ordering of the
error messages are constant between implementations and systems.

\begin{quote}
\begin{tabular}{lll}
   {\tt ERRORTEXT(20)} & $\rightarrow$ & {\tt 'Symbol expected'}\\
   {\tt ERRORTEXT(30)} & $\rightarrow$ & {\tt 'Name or string too long'}\\
   {\tt ERRORTEXT(40)} & $\rightarrow$ & {\tt 'Incorrect call to routine'}\\
\end{tabular}
\end{quote}




\heading{FORM()}{\rexxfunc}

Returns the current ``form'', in which numbers are presented when
exponential form is used. This might be either {\tt SCIENTIFIC}
(the default) or {\tt ENGINEERING}. This value is set through
the {\tt NUMERIC FORM} clause. For more information, see the
documentation on {\tt NUMERIC}.

\begin{quote}
\begin{tabular}{lll}
   {\tt FORM()} & $\rightarrow$ & {\tt 'SCIENTIFIC' ~/* {\rm\it Maybe} */}\\
\end{tabular}
\end{quote}




\heading{FORMAT({\it number}[,[{\it before}][,[{\it after}][,[{\it 
                                    expp}][,[{\it expt}]]]]])}{\rexxfunc}

This function is used to control the format of numbers, and you may
request the size and format in which the number is written. The
parameter {\it number} is the number to be formated, and it must be a
valid {\sc Rexx} number. note that before any conversion or formatting
is done, this number will be normalized according to the current
setting of {\tt NUMERIC}.

The {\it before} and {\it after} parameters determines how many characters
that are used before and after the decimal point, respectively.
Note that {\it before} does {\bf not} specify the number of digits in
the integer part, it specifies the size of the field in which the
integer part of the number is written. Remember to allocate space in
this field for a minus too, if that is relevant. If the field is not
long enough to hold the integer part (including a minus if relevant),
an error is reported.

The {\it after} parameter will dictate the size of the field in which
the fractional part of the number is written. The decimal point itself
is not a part of that field, but the decimal point will be ommitted if
the field holding the fractional part is empty. If there are less
digits in the number than the size of the field, it is padded with
zeros at the right. If there is more digits then it is possible to fit
into the field, the number will be rounded (not truncated) to fit the
field.

{\it Before} must at least be large enough to hold the integer part of
{\it number}. Therefore it can never be less than {\tt 1}, and never
less than {\tt 2} for negative numbers. The integer field will have no
leading zeros, except a single zero digit if the integer part of {\it
number} is empty.

The parameter {\it expp} the size of the field in which the exponent
is written. This is the size of the numeric part of the exponent, so
the ``{\tt E}'' and the sign comes in addition, i.e.~the real length
if the exponent is two more than {\it expp} specifies. If {\it expp}
is zero, it signalizes that exponential form should not be used.
{\it Expp} must be a non-negative whole number. If {\it expp} is
positive, but not large enough to hold the exponent, an error is
reported. 

{\it Expt} is the trigger value that decides when to switch from
simple to exponential form. Normally, the default precision ({\tt
NUMERIC DIGITS}) is used, but if {\it expt} is set, it will override
that. Note that if {\it expt} is set to zero, exponential form will
always be used. However, if {\it expt} tries to force exponential
form, simple form will still be used if {\it expp} is zero. Negative
values for {\it expt} will give an error. Exponential form is used if
more digits than {\it expt} is needed in the integer part, or more
than twice {\it expt} digits are needed in the fractional part.

Note that the {\it after} number will mean different things in
exponential and simple form.  If {\it after} is set to e.g.~{\tt 3},
then in simple form it will force the precision to 0.001, no matter
the magnitude of the number.  If in exponential form, it will force
the number to 4 digits precision.

\begin{quote}
\begin{tabular}{lll}
   {\tt FORMAT(12.34,3,4)} & $\rightarrow$ & {\tt ' 12.3400'}\\
   {\tt FORMAT(12.34,3,,3,0)} & $\rightarrow$ & {\tt '  1.234E+001'}\\
   {\tt FORMAT(12.34,3,1)} & $\rightarrow$ & {\tt ' 12.3400'}\\
   {\tt FORMAT(12.34,3,0)} & $\rightarrow$ & {\tt ' 12.3'}\\
   {\tt FORMAT(12.34,3,4)} & $\rightarrow$ & {\tt ' 12'}\\
   {\tt FORMAT(12.34,,,,0)} & $\rightarrow$ & {\tt '1.234E+1'}\\
   {\tt FORMAT(12.34,,,0)} & $\rightarrow$ & {\tt '12.34'}\\
   {\tt FORMAT(12.34,,,0,0)} & $\rightarrow$ & {\tt '12.34'}\\
\end{tabular}
\end{quote}





\heading{FUZZ()}{\rexxfunc}

Returns the current number of digits which are ignored when comparing
numbers, during operations like {\tt =} and {\tt >}. The default value
for this is {\tt 0}. This value is set using the {\tt NUMERIC FUZZ}
statement, for more information see that.

\begin{quote}
\begin{tabular}{lll}
   {\tt FUZZ()} & $\rightarrow$ & {\tt '0' ~/* {\rm\it Maybe} */}\\
\end{tabular}
\end{quote}



\heading{INSERT({\it string1},{\it string2}[,{\it position}[,{\it
          length}[,{\it padchar}]]])}{\rexxfunc}

Returns the result of inserting {\it string1} into a copy of {\it
string2}. If {\it position} is specified, it marks the character in
{\it string2} which {\it string1} it to be inserted after. {\it
Position} must be a non-negative whole number, and it defaults to {\tt
0}, which means that {\it string2} is put in front of the first
character in {\it string1}.

If {\it length} is specified, {\it string1} is truncated or padded on
the right side to make it excatly {\it length} characters long before
it is inserted. If padding occurs, then {\it padchar} is used, or {\sc
space} if {\it padchar} is undefined. 

\begin{quote}
\begin{tabular}{lll}
   {\tt INSERT('first', 'SECOND')} & $\rightarrow$ & {
                                   \tt 'SECONDfirst'}\\
   {\tt INSERT('first', 'SECOND', 3)} & $\rightarrow$ & {
                                   \tt 'fiSECONDrst'}\\
   {\tt INSERT('first', 'SECOND', 3, 10)} & $\rightarrow$ & {
                                   \tt 'fiSECOND    rst'}\\
   {\tt INSERT('first', 'SECOND', 3, 10, '*')} & $\rightarrow$ & {
                                   \tt 'fiSECOND****rst'}\\
   {\tt INSERT('first', 'SECOND', 3, 4)} & $\rightarrow$ & {
                                   \tt 'fiSECOrst'}\\
   {\tt INSERT('first', 'SECOND', 8)} & $\rightarrow$ & {
                                   \tt 'first  SECOND'}
\end{tabular}
\end{quote}




\heading{LASTPOS({\it needle},{\it haystack}[,{\it start}])}{\rexxfunc}

Searches the string {\it haystack} for the string {\it needle}, and
returns the position in {\it haystack} of the first character in the
substring that matched {\it needle}. The search is started from the
right side, so if {\it needle} occurs several times, the last
occurence is reported. 

If {\it start} is specified, the search starts at character number
{\it start} in {\it haystack}. Note that the standard only states that
the search starts at the {\it start}\/th character. It is not stated
whether a match can partly be to the right of the {\it start}
position, so some implementations may differ on that point. 


\begin{quote}
\begin{tabular}{lll}
   {\tt LASTPOS('be', To be or not to be')} & $\rightarrow$ & {\tt 17}\\
   {\tt LASTPOS('to', to be or not to be', 10)} & $\rightarrow$ & {\tt 3}\\
   {\tt LASTPOS('is', to be or not to be')} & $\rightarrow$ & {\tt 0}\\
   {\tt LASTPOS('to', to be or not to be', 0)} & $\rightarrow$ & {\tt 0}\\
\end{tabular}
\end{quote}



\heading{LEFT({\it string},{\it length}[,{\it padchar}])}{\rexxfunc}

Returns the {\it length} leftmost characters in {\it string}. If {\it
length} (which must be a non-negative whole number) is greater than
the length of {\it string}, the result is padded on the right with 
{\sc space} (or {\it padchar} if that is specified) to make it the
correct length.

\begin{quote}
\begin{tabular}{lll}
   {\tt LEFT('Foo bar', 5)} & $\rightarrow$ & {\tt 'Foo b'}\\
   {\tt LEFT('Foo bar', 3)} & $\rightarrow$ & {\tt 'Foo'}\\
   {\tt LEFT('Foo bar', 10)} & $\rightarrow$ & {\tt 'Foo bar   '}\\
   {\tt LEFT('Foo bar', 10, '*')} & $\rightarrow$ & {\tt 'Foo bar***'}
\end{tabular}
\end{quote}


\heading{LENGTH({\it string})}{\rexxfunc}

Returns the number of characters in {\it string}.

\begin{quote}
\begin{tabular}{lll}
   {\tt LENGTH('')} & $\rightarrow$ & {\tt '0'}\\
   {\tt LENGTH('Foo')} & $\rightarrow$ & {\tt '3'}\\
   {\tt LENGTH('Foo bar')} & $\rightarrow$ & {\tt '7'}\\
   {\tt LENGTH(' foo  bar ')} & $\rightarrow$ & {\tt '10'}
\end{tabular}
\end{quote}



\heading{LINEIN([{\it streamid}][,[{\it line}][,{\it count}]])}{\rexxfunc}

Returns a line read from a file. When only {\it streamio} is
specified, the reading starts at the current read position and
continues to the first End-Of-Line (EOL) mark. Afterwards, the current
read position is set to the character after the EOL mark which
terminated the read-operation. If the operating system uses special
characters for EOL marks, these are not returned by as a part of the
string read..

The default value for {\it streamid} is default input stream. The
format and range of the string {\it streamid} are implementation
dependent.

The {\it line} parameter (which must be a positive whole number) might
be specified to set the current position in the file to the beginning
of line number {\it line} before the read operation starts. If {\it line}
is unspecifiedified, the current position will not be changed before
the read operation. Note that {\it line} is only valid for persistent
steams. For transient streams, an error is reported if {\it line} is
specified. The first line in the stream is numbered {\tt 1}.

{\it Count} specifies the number of lines to read. However, it can
only take the values {\tt 0} and {\tt 1}. When it is {\tt 1} (which is the
default), it will read one line. When it is {\tt 0} it will not read any
lines, and a nullstring is returned. This has the effect of setting
the current read position of the file if {\it line} was specified.

What happens when the functions finds a End-Of-File (EOF) condition is
to some extent implementation dependant. The implementation may
interpret the EOF as an implicit End-Of-Line (EOL) mark is none such
was explicitly present. The implementation may also choose to raise
the {\tt NOTREADY} condition flag (this condition is new from {\rexx}
language level 4.00).

Whether or not {\it stream} must be explicitly opened before a read
operation can be performed, is implementation dependent. In many
implementations, a read or write operation will implicitly open the
stream if not already open.

Assuming that the file {\tt /tmp/file} contains the three lines:
``{\it First line}'', {\it Second line}'' and
``{\it Third line}'':

\begin{quote}
\begin{tabular}{lll}
   {\tt LINEIN('/tmp/file', 1)} & $\rightarrow$ & {\tt 'First line'}\\
   {\tt LINEIN('/tmp/file')} & $\rightarrow$ & {\tt 'Second line'}\\
   {\tt LINEIN('/tmp/file', 1, 0)} & $\rightarrow$ & 
                         {\tt '' ~/* {\rm\it But sets read position */}}\\
   {\tt LINEIN('/tmp/file')} & $\rightarrow$ & {\tt 'First line'}\\
   {\tt LINEIN()} & $\rightarrow$ & {\tt 'Hi, there!' ~/* {\rm\it maybe} */}
\end{tabular}
\end{quote}



\heading{LINEOUT([{\it streamid}][,[{\it string}][,{\it line}]])}{\rexxfunc}

Returns the number of lines remaining after having positioned the
stream {\it streamid} to the start of line {\it line} and written out
{\it string} as a line of text. If {\it streamid} is omitted, the
default output stream is used. If {\it line} (which must be a positive
whole number) is omitted, the stream will not be repositioned before
the write. If {\it string} is omitted, nothing is written to the
stream.  If {\it string} is specified, a system-specific action is
taken after it has been written to stream, to mark a new line.

The format and contents of the first parameter will depend upon the
implementation and how it names streams. Consult
implementation-specific documentation for more information. 

If {\it string} is specified, but not {\it line}, the effect is to
write {\it string} to the stream, starting at the current write
position. If {\it line} is specified, but not {\it string}, the effect
is only to position the stream at the new position. Note that the {\it
line} parameter is only legal if the stream is persistent; you can not
position the current write position for transient streams.

If neither {\it line} nor {\it string} is specified, the standard
requires that the current write position is set the end of the stream,
and implementation specific side-effects may occur. In practice, this
means that an implementation can use this situation to do things like
closeing the stream, or flushing the output. Consult the
implementation specific documentation for more information.

Also note that the return value of this functions may be of little or
no value, If just a half line is written, {\tt 1} may still be
returned, and there are no way of finding out how much (if any) of
{\it string} was written. If {\it string} is not specified, the return
value will always be {\tt 0}, even if {\tt LINEOUT()} was not able to
correctly position the stream.

If it is impossible to correctly write {\it string} to the stream, the
{\tt NOTREADY} flag will be raised. It is not defined whether or not
the {\tt NOTREADY} flag is raised when {\tt LINEOUT()} is used for
positioning, and this is not possible. 

Note that if you write {\it string} to a line in the middle of the
stream (i.e.~{\it line} is less than the total number of lines in the
stream), then the behavior is system and implementation specific. Some
systems will truncate the stream after the newly written line, other
will only truncate if the newly written line has a different length
than the old line which it replaced, and yet other systems will
overwrite and never truncate.

In general, consult your system and implementation specific
documentation for more information about this function. You can safely
assume very little about how it behaves. 

\begin{quote}
\begin{tabular}{lll}
   {\tt LINEOUT(, 'First line')} & $\rightarrow$ & {\tt '1'}\\
   {\tt LINEOUT('/tmp/file', 'Second line', 2)} & $\rightarrow$ & {\tt '1'}\\
   {\tt LINEOUT('/tmp/file', 'Third line')} & $\rightarrow$ & {\tt '1'}\\
   {\tt LINEOUT('/tmp/file', 'Fourth line', 4)} & $\rightarrow$ & {\tt '0'}
\end{tabular}
\end{quote}





\heading{LINES([{\it streamid}])}{\rexxfunc}

Returns the number of complete lines remaining in the named file {\it
stream}. A complete line is not really as complete as the name might
indicate; a complete line is zero or more characters, followed by an
End-Of-Line (EOL) marker. So, if you have read half a line already, you
still have a ``complete'' line left. Note that it is not defined what
to do with a half-finished line at the end of a file. Some interpreters
might interpret the End-Of-File as an implicit EOL mark too, while
others might not. 

The format and contents of the stream {\it streamid} is system and
implementation dependent. If omitted, the default input stream
will be used.

The standard says that if it is impossible (or maybe just difficult)
to accurately count the remaining lines in a stream, {\tt LINES()} can
return {\tt 0} for no more lines, and {\tt 1} for more lines. This
probably applies for all transient streams, as the interpreter
can not reposition in these files, and can therefore not count the
number of remaining lines. It can also apply for persistent files, if
the operation of counting the lines left in the file is very
timeconsuming.

As a result, defensive programming indicates that you can safely only
assume that this function will return either {\tt 0} or a non-zero
result. If you want to use the non-zero result to more than just an
indicator on whether more lines are available, you must check that it
is larger than one. If so, you can safely assume that it hold the
number of available lines left.

As with all the functions operating on streams, you can safely assume
very little about this function, so consult the system and
implementation specific documentation. 

\begin{quote}
\begin{tabular}{lll}
   {\tt LINES()} & $\rightarrow$ & {\tt '1' ~/* {\rm\it Maybe} */}\\
   {\tt LINES()} & $\rightarrow$ & {\tt '0' ~/* {\rm\it Maybe} */}\\
   {\tt LINES('/tmp/file')} & $\rightarrow$ & {\tt '2' ~/* {\rm\it Maybe} */}\\
   {\tt LINES('/tmp/file')} & $\rightarrow$ & {\tt '1' ~/* {\rm\it Maybe} */}
\end{tabular}
\end{quote}




\heading{MAX({\it number1}[,{\it number2}]...)}{\rexxfunc}

Takes any positive number of parameters, and will return the parameter
that had the highest numerical value. The parameters may be any valid
{\rexx} number. The number that is returned, is normalized according
to the current settings of {\tt NUMERIC}, so the result need not be
strictly equal to any of the parameters.

Actually, the standard says that the value returned is the first
number in the parameterlist which is equal to the result of adding a
positive number or zero to any of the other parameters. Note that this
definition opens for ``strange'' results if you are brave enough to
play around with the settings of {\tt NUMERIC FUZZ}.


\begin{quote}
\begin{tabular}{lll}
   {\tt MAX(1, 2, 3, 5, 4)} & $\rightarrow$ & {\tt '5'}\\
   {\tt MAX(6)} & $\rightarrow$ & {\tt '6'}\\
   {\tt MAX(-4, .001E3, 4)} & $\rightarrow$ & {\tt '4'}\\
   {\tt MAX(1, 2, 05.0, 4)} & $\rightarrow$ & {\tt '5.0'}
\end{tabular}
\end{quote}





\heading{MIN({\it number}[,{\it number}]...)}{\rexxfunc}

Like {\tt MAX()}, except that the lowest numerical value is
returned. For more information, see {\tt MAX()}.

\begin{quote}
\begin{tabular}{lll}
   {\tt MAX(5, 4, 3, 1, 2)} & $\rightarrow$ & {\tt '1'}\\
   {\tt MAX(6)} & $\rightarrow$ & {\tt '6'}\\
   {\tt MAX(-4, .001E3, 4)} & $\rightarrow$ & {\tt '-4'}\\
   {\tt MAX(1, 2, 05.0E-1, 4)} & $\rightarrow$ & {\tt '0.50'}
\end{tabular}
\end{quote}




\heading{OVERLAY({\it string1},{\it string2}[,[{\it start}][,[{\it
                   length}][,{\it padchar}]]])}{\rexxfunc}

Returns a copy of {\it string2}, totally or partially overwritten by
{\it string1}. If these are the only arguments, the overwriting starts
at the first character in {\it string2}.

If {\it start} is specified, the first character in {\it string1}
overwrites character number {\it start} in {\it string2}. {\it Start}
must be a positive whole number, and defaults to {\tt 1}, i.e.~the the
first character of {\it string1}.  If the {\it start} position is to
the right of the end of {\it string2}, then {\it string2} is padded at
the right hand end to make it {\it start}{\tt -}1 characters long,
before {\it string1} is added.

If {\it length} is specified, then {\it string2} will be stripped or
padded at the right hand end to match the specified length. For
padding (of both strings) {\it padchar} will be used, or {\sc space}
if {\it padchar} is unspecified. {\it Length} must be non-negative, and
defaults to the length of {\it string1}.

\begin{quote}
\begin{tabular}{lll}
   {\tt OVERLAY('NEW', 'old-value')} & $\rightarrow$ & {
                                   \tt 'NEW-value'}\\
   {\tt OVERLAY('NEW', 'old-value', 3)} & $\rightarrow$ & {
                                   \tt 'oldNEWlue'}\\
   {\tt OVERLAY('NEW', 'old-value', 3, 5)} & $\rightarrow$ & {
                                   \tt 'oldNEW  e'}\\
   {\tt OVERLAY('NEW', 'old-value', 3, 5), '*')} & $\rightarrow$ & {
                                   \tt 'oldNEW**e'}\\
   {\tt OVERLAY('NEW', 'old-value', 3, 2)} & $\rightarrow$ & {
                                   \tt 'oldNEalue'}\\
   {\tt OVERLAY('NEW', 'old-value', 8)} & $\rightarrow$ & {
                                   \tt 'old-valuNEW'}\\
   {\tt OVERLAY('NEW', 'old-value', 10)} & $\rightarrow$ & {
                                   \tt 'old-value  NEW'}\\
   {\tt OVERLAY('NEW', 'old-value', 8,, '*')} & $\rightarrow$ & {
                                   \tt 'old-value**NEW'}\\
   {\tt OVERLAY('NEW', 'old-value', 8, 5, '*')} & $\rightarrow$ & {
                                   \tt 'old-value**NEW**'}
\end{tabular}
\end{quote}





\heading{POS({\it needle},{\it haystack}[,{\it start}])}{\rexxfunc}

Seeks for an occurrance of the string {\it needle} in the string {\it
haystack}. If {\it needle} is not found, then {\tt 0} is returned.
Else, the position in {\it haystack} of the first character in the
part that matched is returned, which will be a positive whole number.
If {\it start} (which must be a positive whole number) is specified,
the search for {\it needle} will start at position {\it start} in {\it
haystack}.

\begin{quote}
\begin{tabular}{lll}
   {\tt POS('be', 'to be or not to be')} & $\rightarrow$ & {\tt 3}\\
   {\tt POS('to', 'to be or not to be', 10)} & $\rightarrow$ & {\tt 17}\\
   {\tt POS('is', 'to be or not to be')} & $\rightarrow$ & {\tt 0}\\
   {\tt POS('to', 'to be or not to be', 18)} & $\rightarrow$ & {\tt 0}
\end{tabular}
\end{quote}




\heading{QUEUED()}{\rexxfunc}
\label{bif:queued}

Returns the number of lines currently in the external data queue (the
``stack''). Note that the stack is a concept external to {\rexx}, this
function may depend on the implementation and system Consult the
system specific documentation for more information.

\begin{quote}
\begin{tabular}{lll}
   {\tt QUEUED()} & $\rightarrow$ & {\tt '0' ~/* {\rm\it Maybe} */}\\
   {\tt QUEUED()} & $\rightarrow$ & {\tt '42' ~/* {\rm\it Maybe} */}
\end{tabular}
\end{quote}



\heading{RANDOM({\it max})}{\rexxfunc}\vspace{-5mm}
\heading{RANDOM([{\it min}][,[{\it max}][,{\it seed}]])}{\rexxfunc}

Returns a pseudo-random whole number. If called with only the first
parameter, the first format will be used, and the number returned will
be in the range {\tt 0} to the value of the first parameter,
inclusive. Then the parameter {\it max} must be a non-negative whole
number, not greater than 100000.

If called with more than one parameter, or with one parameter, which
is not the first, the second format will be used. Then {\it min} and
{\it max} must be whole numbers, and {\it max} can not be less than
{\it min}, and the difference {\it max}{\tt -}{\it min} can not be more
than 100000. If one or both of them is unspecified, the default for {\it
min} is {\tt 0}, and the default for {\it max} is {\tt 999}. Note that
both {\it min} and {\it max} are allowed to be negative, as long as
their difference is within the requirements mentioned. 

If {\it seed} is specified, you may control which numbers the
pseudo-random algoritm will generate. If you do not specify it, it will
be set to some ``random'' value at the first call to {\tt RANDOM()}
(typically a function of the time). When specifying {\it seed}, 
it will effect the result of the current call to {\tt RANDOM()}.

The standard does not require that a specific method is to be used for
generating the pseudorandom numbers, so the reproducability can only
be guaranteed as long as you use the same implementation on the same
machine, using the same operating system. If any of these change, a
given {\it seed} may produce a different sequence of pseudo-random
numbers. 

Note that depending on the implementation, some numbers might have a
slightly increased chance of turning up than other. If the {\rexx}
implementation uses a 32 bit pseudo-random generator provided by the
operating system and returns the remainder after integer dividing it
by the difference of {\it min} and {\it max}, low numbers are
favorized if the $2^{32}$ is not a multiple of that difference.
Supposing that the call is {\tt RANDOM(100000)} and the pseudo-random
generator generates any 32 bit number with equal chance, the change of
getting a number in the range 0{\tt -}67296 is about 0.000010000076,
while the changes of getting a number in the range 67297{\tt
-}100000 is about 0.000009999843.

A much worse problem with pseudo-random numbers are that they
sometimes do not tend to be random at all. Under one operating system
(name withheld to protect the guilty), the system's pseudo-random
routine returned numbers where the last binary digit alternated
between 0 and 1. On that machine, {\tt RANDOM(1)} would return the
series 0, 1, 0, 1, 0, 1, 0, 1 etc, which is hardly random at all. You
should therefore never trust the pseudo-random routine to give you
random numbers.

Note that due to the special syntax, there is a big difference between
using {\tt RANDOM(10)} and {\tt RANDOM(10,)}. The former will give a
pseudo-random number in the range 0{\tt -}10, while the latter will
give a pseudo-random number in the range 10{\tt -}999.

Also note that it is not clear whether the standard allows {\it min}
to be equal to {\it max}, so to program compatible, make sure that
{\it max} is always larger than {\it min}.

\begin{quote}
\begin{tabular}{lll}
   {\tt RANDOM()} & $\rightarrow$ & {\tt '123' 
                                         ~/* {\rm\it Between 0 and 999} */}\\
   {\tt RANDOM(10)} & $\rightarrow$ & {\tt '5' 
                                         ~/* {\rm\it Between 0 and 10} */}\\
   {\tt RANDOM(, 10)} & $\rightarrow$ & {\tt '3' 
                                         ~/* {\rm\it Between 0 and 10} */}\\
   {\tt RANDOM(20, 30)} & $\rightarrow$ & {\tt '27' 
                                         ~/* {\rm\it Between 20 and 30} */}\\
   {\tt RANDOM(,, 12345)} & $\rightarrow$ & {\tt '765' 
                            ~/* {\rm\it Between 0 and 999, and sets seed} */}
\end{tabular}
\end{quote}


\heading{REVERSE({\it string})}{\rexxfunc}

Returns a string of the same length as {\it string}, but having the
order of the characters reversed.

\begin{quote}
\begin{tabular}{lll}
   {\tt REVERSE('FooBar')} & $\rightarrow$ & {\tt 'raBooF'}\\
   {\tt REVERSE('  Foo Bar')} & $\rightarrow$ & {\tt 'raB ooF  '}\\
   {\tt REVERSE('3.14159')} & $\rightarrow$ & {\tt '95141.3'}\\
\end{tabular}
\end{quote}




\heading{RIGHT({\it string},{\it length}[,{\it padchar}])}{\rexxfunc}

Returns the {\it length} rightmost characters in {\it string}. If {\it
length} (which must be a non-negative whole number) is greater than
the length of {\it string} the result is padded on the left with the
necessary number of {\it padchar}s to make it as long as {\it length}
specifies. {\it Padchar} defaults to {\sc space}.

\begin{quote}
\begin{tabular}{lll}
   {\tt RIGHT('Foo bar', 5)} & $\rightarrow$ & {\tt 'o bar'}\\
   {\tt RIGHT('Foo bar', 3)} & $\rightarrow$ & {\tt 'bar'}\\
   {\tt RIGHT('Foo bar', 10)} & $\rightarrow$ & {\tt '   Foo bar'}\\
   {\tt RIGHT('Foo bar', 10, '*')} & $\rightarrow$ & {\tt '***Foo bar'}
\end{tabular}
\end{quote}




\heading{SIGN({\it number})}{\rexxfunc}

Returns either {\tt -1}, {\tt 0} or {\tt 1}, depending on whether {\it
number} is negative, zero, or positive, respectively. {\it Number}
must be a valid {\rexx} number, and are normalized according to the
current settings of {\tt NUMERIC} before comparisation.

\begin{quote}
\begin{tabular}{lll}
   {\tt SIGN(-12)} & $\rightarrow$ & {\tt '-1'}\\
   {\tt SIGN(42)} & $\rightarrow$ & {\tt '1'}\\
   {\tt SIGN(-0.00000012)} & $\rightarrow$ & {\tt '-1'}\\
   {\tt SIGN(0.000)} & $\rightarrow$ & {\tt '0'}\\
   {\tt SIGN(-0.0)} & $\rightarrow$ & {\tt '0'}
\end{tabular}
\end{quote}



\heading{SOURCELINE([{\it lineno}])}{\rexxfunc}

If {\it lineno} (which must be a positive whole number) is specified,
this function will return a string containing a copy of the {\rexx}
script source code on that line. If {\it lineno} is greater than the
number of lines in the {\rexx} script source code, an error is
reported.

If {\it lineno} is unspecified, the number
of lines in the {\rexx} script source code is returned.

Note that from {\rexx} language level 3.50 to 4.00, the requirements
of this function were relaxed to simplify execution when the source
code is not available (compiled or preparsed {\rexx}). An
implementation might make two simplifications: to return {\tt 0} if
called without parameter. If so, any call to {\tt SOURCELINE()} with a
parameter will generate an error. The other simplification is to
return a nullstring for any call to {\tt SOURCELINE()} with a legal
parameter.

Note that the code executed by the {\tt INTERPRET} clause can not be
retrieved by {\tt SOURCELINE()}.

\begin{quote}
\begin{tabular}{lll}
   {\tt SOURCELINE()} & $\rightarrow$ & {\tt '42' ~/* {\rm\it Maybe} */}\\
   {\tt SOURCELINE(1)} & $\rightarrow$ & 
                          {\tt '/* {\rm\it This Rexx script will ...} */'}\\
   {\tt SOURCELINE(23)} & $\rightarrow$ & {\tt '   var = 12 
                                                 ~/* {\rm\it Maybe} */'}
\end{tabular}
\end{quote}



\heading{SPACE({\it string}[,[{\it length}][,{\it padchar}]])}{\rexxfunc}

With only one parameter {\it string} is returned, stripped of any
trailing or leading blanks, and any consequitive blanks inside {\it
string} translated to a single {\sc space} character (or {\it padchar}
if specified).

{\it Length} must be a non-negative whole number. If specified,
consequitive blanks within {\it string} is replaced by exactly {\it
length} instances of {\sc space} (or {\it padchar} if specified).
However, {\it padchar} will only be used in the output string, in the
input string, blanks will still be the ``magic'' characters. As a
consequence, if there exist any {\it padchar}s in {\it string}, they
will remain untouched and will not affect the spacing.

\begin{quote}
\begin{tabular}{lll}
   {\tt SPACE(' Foo  bar ')} & $\rightarrow$ & {\tt 'Foo bar'}\\
   {\tt SPACE(' Foo  bar ', 2)} & $\rightarrow$ & {\tt 'Foo  bar'}\\
   {\tt SPACE(' Foo  bar ',, '*')} & $\rightarrow$ & {\tt 'Foo*bar'}\\
   {\tt SPACE('Foo bar', 3, '-')} & $\rightarrow$ & {\tt 'Foo---bar'}\\
   {\tt SPACE('Foo  bar',, 'o')} & $\rightarrow$ & {\tt 'Fooobar'}
\end{tabular}
\end{quote}



\heading{STEAM({\it streamid}[,{\it option}[,{\it command}]])}{\rexxfunc}
\label{BIF:stream}

This function was added to {\rexx} in language level 4.00. It provides
a general machanism for doing operations on streams. However, very
little is specified about how the internal of this function should
work, so you should consult the implementation specific documentation
for more information.

The {\it streamid} identifies a stream. The actual contents and format
of this string is implementation dependant. 

The {\it option} selects one of several operations which {\tt
STREAM()} is to perform. The possible operations are:
\begin{itemize}
\item[{\tt C}]
   (Command) If this option is selected, a third parameter must be
   present, {\it command}, which is the command to be performed on the
   stream. The contents of {\it command} is implementation dependant. 

\item[{\tt D}]
   (Description) Returns a description of the state of {\it streamid}.
   The return value is implementation dependant.

\item[{\tt S}]
   (State) Returns a state which describes the state of {\it
   streamid}. The standard requires that it is one of the following:
   {\tt ERROR}, {\tt NOTREADY}, {\tt READY} and {\tt UNKNOWN}. The
   meaning of these are described in the chapter about stream I/O. 
\end{itemize}

Note that the options {\tt Description} and {\tt State} really have
the same function, but that {\tt State} in general is implementation
independant, while {\tt Description} is implementation dependant.




\heading{STRIP({\it string}[,[{\it option}][,{\it char}]])}{\rexxfunc}

Returns {\it string} after possibly stripping it of any number of
leading and/or trailing characters. The default action is to strip off
both leading and trailing blanks. If {\it char} (which must be a
string containing exactly one character) is specified, that
character will be stripped off instead of blanks. Interword blanks (or
{\it char}s if defined, that are not leading of trailing) are untouched.

If {\it option} is specified, it will define what to strip. The
possible values for {\it option} are:
\begin{itemize}
\item[{\tt L}]
   (Leading) Only strip off leading blanks, or {\it char}s if specified.

\item[{\tt T}]
   (Trailing) Only strip off trailing blanks, or {\it char}s if
   specified.

\item[{\tt B}]
   (Both) Combine the effect of {\tt L} and {\tt T}, that is, strip off
   both leading and trailing blanks, or {\it char}s if it is
   specified.  This is the default action.
\end{itemize}

\begin{quote}
\begin{tabular}{lll}
   {\tt STRIP(' Foo ~bar ')} & $\rightarrow$ & {\tt 'Foo ~bar'}\\
   {\tt STRIP(' Foo ~bar ', 'L')} & $\rightarrow$ & {\tt 'Foo ~bar '}\\
   {\tt STRIP(' Foo ~bar ', 't')} & $\rightarrow$ & {\tt ' Foo ~bar'}\\
   {\tt STRIP(' Foo ~bar ', 'Both')} & $\rightarrow$ & {\tt 'Foo ~bar'}\\
   {\tt STRIP('0.1234500',, '0')} & $\rightarrow$ & {\tt '.12345'}\\
   {\tt STRIP('0.1234500 ',, '0')} & $\rightarrow$ & {\tt '.1234500'}
\end{tabular}
\end{quote}




\heading{SUBSTR({\it string},{\it start}[,[{\it length}][,{\it
          padchar}]])}{\rexxfunc}

Returns the substring of {\it string} that starts at {\it start}, and
has the length {\it length}. {\it Length} defaults to the rest of the
string. {\it Start} must be a positive whole, while {\it length} can
be any non-negative whole number.

It is not an error for {\it start} to be larger than the length of
{\it string}.  If {\it length} is specified and the sum of {\it
length} and {\it start} minus 1 is greater that the length of {\it
string}, then the result will be padded with {\it padchar}s to the
specified length. The default value for {\it padchar} is the {\sc
space} character.

\begin{quote}
\begin{tabular}{lll}
   {\tt SUBSTR('Foo bar', 3)} & $\rightarrow$ & {\tt 'o bar'}\\
   {\tt SUBSTR('Foo bar', 3, 3)} & $\rightarrow$ & {\tt 'o b'}\\
   {\tt SUBSTR('Foo bar', 4, 6)} & $\rightarrow$ & {\tt ' bar  '}\\
   {\tt SUBSTR('Foo bar', 4, 6, '*')} & $\rightarrow$ & {\tt ' bar**'}\\
   {\tt SUBSTR('Foo bar', 9, 4, '*')} & $\rightarrow$ & {\tt '****'}
\end{tabular}
\end{quote}



\heading{SUBWORD({\it string},{\it start}[,{\it length}])}{\rexxfunc}

Returns the part of {\it string} that starts at blankdelimited word
{\it start} (which must be a positive whole number). If {\it length}
(which must be a non-negative whole number) is specified, that number
of words are returned. The default value for {\it length} is the rest
of the string.

It is not an error to specify {\it length} to refer to more words than
{\it string} contains, or for {\it start} and {\it length} together to
specify more words than {\it string} holds. The result string will be
stripped of any leading and trailing blanks, but interword blanks will
be preserved as is. 

\begin{quote}
\begin{tabular}{lll}
   {\tt SUBWORD('To be or not ~to be', 4)} & $\rightarrow$ & 
                                              {\tt 'not ~to be'}\\
   {\tt SUBWORD('To be or not ~to be', 4, 2)} & $\rightarrow$ & 
                                              {\tt 'not ~to'}\\
   {\tt SUBWORD('To be or not ~to be', 4, 5)} & $\rightarrow$ & 
                                              {\tt 'not ~to be'}\\
   {\tt SUBWORD('To be or not ~to be', 1, 3)} & $\rightarrow$ & 
                                              {\tt 'To be or'}
\end{tabular}
\end{quote}



\heading{SYMBOL({\it name})}{\rexxfunc}

Checks if the string {\it name} is a valid symbol (a positive number
or a possible variable name), and returns a three letter string indicating the result
of that check.  If {\it name} is a symbol, and names a currently set
variable, {\tt VAR} is returned, if {\it name} is a legal symbol name,
but has not a been given a value (or is a constant symbol, which can
not be used as a variable name), {\tt LIT} is returned to signify
that it is a literal.  Else, if {\it name} is not a legal symbol name
the string {\tt BAD} is returned.

Watch out for the effect of ``double expansion''. {\it Name} is
interpreted as an expression evaluating naming the symbol to be
checked, so you might have to quote the parameter. 

\begin{quote}
\begin{tabular}{lll}
   {\tt SYMBOL('Foobar')} & $\rightarrow$ & {\tt 'VAR' ~/* {\rm\it Maybe} */}\\
   {\tt SYMBOL('Foo bar')} & $\rightarrow$ & {\tt 'BAD'}\\
   {\tt SYMBOL('Foo.Foo bar')} & $\rightarrow$ & {\tt 'VAR' 
                                                       ~/* {\rm\it Maybe} */}\\
   {\tt SYMBOL('3.14')} & $\rightarrow$ & {\tt 'LIT'}\\
   {\tt SYMBOL('.Foo->bar')} & $\rightarrow$ & {\tt 'BAD'}
\end{tabular}
\end{quote}



\heading{TIME([{\it option}])}{\rexxfunc}
\label{bif:time}

Returns a string containing information about the time. To get the
time in a particular format, an {\it option} can be
specified. The default {\it option} is {\tt Normal}. The meaning of the
possible options are:
\begin{itemize}
\item[{\tt C}]
   (Civil) Returns the time in civil format.  The return value might
   be ``{\tt hh:mmXX}'', where {\tt XX} are either {\tt am} or {\tt
   pm}. The {\tt hh} part will be stripped of any leading zeros, and
   will be in the range 1{\tt -}12 inclusive.

\item[{\tt E}]
   (Elapsed) Returns the time elapsed in seconds since the internal
   stopwatch was started.  The result will not have any leading zeros
   or blanks.  The output will be a floating point number with six
   digits after the decimal point.

\item[{\tt H}]
   (Hours) Returns the number of complete hours that have passed since
   last midnight in the form ``{\tt hh}''. The output will have no leading
   zeros, and will be in the range 0{\tt -}23.

\item[{\tt L}]
   (Long) Returns the exact time, down to the microsecond. This is
   called the long format. The output might be ``{\tt hh:mm:ss.mmmmmm}''.
   Be aware that most computers do not have a clock of that
   accuracy, so the actual granularity you can expect, will
   be about a few milliseconds. The {\tt hh}, {\tt mm} and {\tt ss}
   parts will be identical to what is returned by the options {\tt H},
   {\tt M} and {\tt S} respectively, except that each part will have
   leading zeros as indicated by the format.

\item[{\tt M}]
   (Minutes) Returns the number of complete minutes since midnight, in
   a format having no leading zeros, and will be in the range 0{\tt
   -}59.

\item[{\tt N}]
   (Normal) 
   The output format is ``{\tt hh:mm:ss}'', and is padded with zeros if
   needed. The {\tt hh}, {\tt mm} and {\tt ss} will contain the hours,
   minutes and seconds, respectively. Each part will be padded with
   leading zeros to make it double-digit. 

\item[{\tt R}]
   (Reset) Returns the value of the internal stopwatch just like the
   {\tt E} option, and using the same format. In addition, it will
   reset the stopwatch to zero after its contents has been read.

\item[{\tt S}]
   (Seconds) Returns the number of complete seconds since midnight, in
   a format having no leading spaces, and will be in the range $0-59$.
\end{itemize}

Note that the time is never rounded, only truncated. As shown in the
examples below, the seconds do not get rounded upwards, even though
the decimal part implies that they are closer to {\tt 59} than to {\tt
58}. The same applies for the minutes, which are closer to {\tt 33}
than to {\tt 32}, but is truncated to {\tt 32}.

None of the formats will have leading or trailing spaces. 

Assuming that the time is exactly 14:32:58.987654, the following will
be true:

\begin{quote}
\begin{tabular}{lll}
   {\tt TIME('C')} & $\rightarrow$ & {\tt '2:32pm'}\\
   {\tt TIME('E')} & $\rightarrow$ & {\tt '0.01200' ~/* {\rm\it Maybe} */}\\
   {\tt TIME('H')} & $\rightarrow$ & {\tt '14'}\\
   {\tt TIME('L')} & $\rightarrow$ & {\tt '14:32:58.987654'}\\
   {\tt TIME('M')} & $\rightarrow$ & {\tt '32'}\\
   {\tt TIME('N')} & $\rightarrow$ & {\tt '14:32:58'}\\
   {\tt TIME('R')} & $\rightarrow$ & {\tt '0.430221' ~/* {\rm\it Maybe} */}\\
   {\tt TIME('S')} & $\rightarrow$ & {\tt '58'}
\end{tabular}
\end{quote}



\heading{TRACE([{\it setting}])}{\rexxfunc}

Returns the current value of the trace setting. If the string {\it
setting} is 
specified, it will be used as the new setting for tracing, after the
old value have be recorded for the return value. Note that
the {\it setting} is not an option, but may be any of the
tracesettings that can be specified to the clause {\tt TRACE}, except
that the numeric variant is not allowed with {\tt TRACE()}. In
practice, this can be a word, of which only the first letter counts, optionally preceded by a
question mark.

\begin{quote}
\begin{tabular}{lll}
   {\tt TRACE()} & $\rightarrow$ & {\tt 'C' ~/* {\rm\it Maybe} */}\\
   {\tt TRACE('N')} & $\rightarrow$ & {\tt 'C'}\\
   {\tt TRACE('?')} & $\rightarrow$ & {\tt 'N'}
\end{tabular}
\end{quote}





\heading{TRANSLATE({\it string}[,[{\it tablein}][,[{\it
           tableout}][,{\it padchar}]]])}{\rexxfunc}

Performs a translation on the characters in {\it string}. As a special
case, if neither {\it tablein} nor {\it tableout} is specified, it
will translate {\it string} from lower case to upper case. Note that
this operation may depend on the language chosen, if your interpreter
supports national character sets.

Two translation tables might be specified as the strings {\it tablein}
and {\it tableout}.  If one or both of the tables are specified, each
character in {\it string} that exists in {\it tablein} is translated
to the character in {\it tableout} that occupies the same position as
the character did in {\it tablein}. The {\it tablein} defaults to the
whole character set (all 256) in numeric sequence, while {\it
tableout} defaults to an empty set. Characters not in {\it tablein}
are left unchanged.

If {\it tableout} is larger than {\it tablein}, the extra entries are
ignored. If it is smaller than {\it tablein} it is padded with {\it
padchar} to the correct length. {\it Padchar} defaults to {\sc space}.

If a character occurs more than once in {\it tablein}, only the first
occurrence will matter.

\begin{quote}
\begin{tabular}{lll}
   {\tt TRANSLATE('FooBar')} & $\rightarrow$ & {\tt 'FOOBAR'}\\
   {\tt TRANSLATE('FooBar', 'ABFORabfor', 'abforABFOR')} & 
                         $\rightarrow$ & {\tt 'fOObAR'}\\
   {\tt TRANSLATE('FooBar', 'abfor')} & $\rightarrow$ & 
                            {\tt 'F ~B ~'}\\
   {\tt TRANSLATE('FooBar, 'abfor',, '\#')} & $\rightarrow$ & 
                             {\tt 'F\#\#B\#\#'}
\end{tabular}
\end{quote}




\heading{TRUNC({\it number}[,{\it length}])}{\rexxfunc}

Returns {\it number} truncated to the number of decimals specified by
{\it length}.  {\it Length} defaults to {\tt 0}, that is return an
whole number with no decimal decimal part.

The decimal point will only be present if the is a non-empty decimal
part, i.e.~{\it length} is non-zero. The number will always be
returned in simple form, never exponential form, no matter what the
current settings of {\it NUMERIC} might be. If {\it length} specifies
more decimals than {\it number} has, extra zeros are appended. If {\it
length} specifies less decimals than {\it number} has, the number is
truncated. Note that {\it number} is never rounded, except for the
rounding that might take place during normalization.

\begin{quote}
\begin{tabular}{lll}
   {\tt TRUNC(12.34)} & $\rightarrow$ & {\tt '12'}\\
   {\tt TRUNC(12.99)} & $\rightarrow$ & {\tt '12'}\\
   {\tt TRUNC(12.34, 4)} & $\rightarrow$ & {\tt '12.3400'}\\
   {\tt TRUNC(12.3456, 2)} & $\rightarrow$ & {\tt '12.34'}
\end{tabular}
\end{quote}





\heading{VALUE({\it symbol}[,[{\it value}],[{\it pool}]])}{\rexxfunc}

This function expects as first parameter string {\it symbol}, which
names an existing variable. The result returned from the function is
the value of that variable. If {\it symbol} does not name an existing
variable, the default value is returned, and the {\tt NOVALUE}
condition is not raised. If {\it symbol} is not a valid symbol name,
and this function is used to access an normal {\rexx} variable, an
error occurs. Be aware of the ``double-expansion'' effect, and quote
the first parameter if necessary.

If the optional second parameter is specified, the variable will be
set to that value, after the old value has been extracted.

The optional parameter {\it pool} might be specified to select a
particular pool of variables to search for {\it symbol}. The contents
and format of {\it pool} is implementation dependant. The default is
to search in the variables at the current procedural level in {\sc
Rexx}. Which {\it pool}s that are available is implementation
dependent, but typically one can set variables in application programs
or in the operating system.

Note that if {\tt VALUE()} is used to access variable in pools outside
the {\rexx} interpreter, the requirements to format (a valid symbol)
will not in general hold. There may be other requirements instead,
depending on the implementation and the system. Depending on the
validity of the name, the value, or whether the variable can be set or
read, the {\tt VALUE()} function can give error messages when
accessing variables in pools other than the normal. Consult the
implementation and system specific documentation for more information.

If it is used to access compound variables inside the interpreter the
tail part of this function can take any expression, even expression
that are not normally legal in {\rexx} scripts source code.

By using this function, it is possible to perform an extra level of
interpretation of a variable.

\begin{quote}
\begin{tabular}{lll}
   {\tt VALUE('FOO')} & $\rightarrow$ & {\tt 'bar'}\\
   {\tt VALUE('FOO', 'new')} & $\rightarrow$ & {\tt 'bar'}\\
   {\tt VALUE('FOO')} & $\rightarrow$ & {\tt 'new'}\\
   {\tt VALUE('USER', 'root', 'SYSTEM')} & $\rightarrow$ & {\tt
                 'guest' ~/* {\rm\it If {\tt SYSTEM} exists} */}\\
   {\tt VALUE('USER',, 'SYSTEM')} & $\rightarrow$ & {\tt 'root'}
\end{tabular}
\end{quote}




\heading{VERIFY({\it string},{\it ref}[,[{\it 
                                    option}][,{\it start}]])}{\rexxfunc}

With only the first two parameters, it will return the
position of the first character in {\it string} that is not also a
character in the string {\it ref}. If all characters in {\it string}
are also in {\it ref}, it will return {\tt 0}.

If {\it option} is specified, it can be one of:
\begin{itemize}
\item[{\tt N}]
   (Nomatch) The result will be the position of the first character in
   {\it string} that does exist in {\it ref}, or zero if all exist in
   {\it ref}. This is the default option.

\item[{\tt M}]
   (Match) Reverses the search, and returns the position of the first
   character in {\it string} that exists in {\it ref}. If none exists
   in {\it ref}, zero is returned.
\end{itemize}

If {\it start} (which must be a positive whole number) is specified,
the search will start at that position in {\it string}. The default
value for {\it start} is {\tt 1}.

\begin{quote}
\begin{tabular}{lll}
   {\tt VERIFY('foobar', 'barfo')} & $\rightarrow$ & {\tt '2'}\\
   {\tt VERIFY('foobar', 'barfo', 'M')} & $\rightarrow$ & {\tt '2'}\\
   {\tt VERIFY('foobar', 'fob', 'N')} & $\rightarrow$ & {\tt '5'}\\
   {\tt VERIFY('foobar', 'barf', 'N', 3)} & $\rightarrow$ & {\tt '3'}\\
   {\tt VERIFY('foobar', 'barf', 'N', 4)} & $\rightarrow$ & {\tt '0'}
\end{tabular}
\end{quote}





\heading{WORD({\it string},{\it wordno})}{\rexxfunc}

Returns the blankdelimited word number {\it wordno} from the string
{\it string}. If {\it wordno} (which must be a positive whole number)
refers to a non-existing word, then a nullstring is returned. The
result will be stripped of any blanks.

\begin{quote}
\begin{tabular}{lll}
   {\tt WORD('To be or not to be', 3)} & $\rightarrow$ & {\tt 'or'}\\
   {\tt WORD('To be or not to be', 4)} & $\rightarrow$ & {\tt 'not'}\\
   {\tt WORD('To be or not to be', 8)} & $\rightarrow$ & {\tt ''}
\end{tabular}
\end{quote}




\heading{WORDINDEX({\it string},{\it wordno})}{\rexxfunc}

Returns the character position of the the first character of 
blankdelimited word number {\it wordno} in {\it string}, which is
interpreted as a string of blankdelimited words.  If {\it
number} (which must be a positive whole number) refers to a word that
does not exist in {\it string}, then {\it 0} is returned.

\begin{quote}
\begin{tabular}{lll}
   {\tt WORDINDEX('To be or not to be', 3)} & $\rightarrow$ & {\tt '7'}\\
   {\tt WORDINDEX('To be or not to be', 4)} & $\rightarrow$ & {\tt '10'}\\
   {\tt WORDINDEX('To be or not to be', 8)} & $\rightarrow$ & {\tt '0'}
\end{tabular}
\end{quote}




\heading{WORDLENGTH({\it string},{\it wordno})}{\rexxfunc}

Returns the number of characters in blankdelimited word number {\it
number} in {\it string}. If {\it number} (which must be a positive
whole number) refers to an non-existent word, then {\tt 0} is
returned. Trailing or leading blanks do not count when calculating the
length. 

\begin{quote}
\begin{tabular}{lll}
   {\tt WORDLENGTH('To be or not to be', 3)} & $\rightarrow$ & {\tt '2'}\\
   {\tt WORDLENGTH('To be or not to be', 4)} & $\rightarrow$ & {\tt '3'}\\
   {\tt WORDLENGTH('To be or not to be', 0)} & $\rightarrow$ & {\tt '0'}\\
\end{tabular}
\end{quote}




\heading{WORDPOS({\it phrase},{\it string}[,{\it start}])}{\rexxfunc}

Returns the word number in {\it string} which indicates at which
{\it phrase} begins, provided that {\it phrase} is a subphrase of {\it
string}. If not, {\tt 0} is returned to indicate that the phrase was not
found. A phrase differs from a substring in one significant way; a
phrase is a set of words, separated by any number of blanks.

For instance, ``{\tt is~~a}'' is a subphrase of ``{\tt
This~is~a~phrase}''. Notice the different amount of whitespace between
``{\tt is}'' and ``{\tt a}''.

If {\it start} is specified, it sets the word in {\it string} at which the
search starts. The default value for {\it start} is {\tt 1}.

\begin{quote}
\begin{tabular}{lll}
   {\tt WORDPOS('or not', 'to be or not to be')} & $\rightarrow$ & {\tt '3'}\\
   {\tt WORDPOS('not to', 'to be or not to be')} & $\rightarrow$ & {\tt '4'}\\
   {\tt WORDPOS('to be', 'to be or not to be')} & $\rightarrow$ & {\tt '1'}\\
   {\tt WORDPOS('to be', 'to be or not to be', 3)} & $\rightarrow$ & {\tt '6'}
\end{tabular}
\end{quote}




\heading{WORDS({\it string})}{\rexxfunc}

Returns the number of blankdelimited words in the {\it string}.

\begin{quote}
\begin{tabular}{lll}
   {\tt WORDS('To be or not to be')} & $\rightarrow$ & {\tt '6'}\\
   {\tt WORDS('Hello world')} & $\rightarrow$ & {\tt '2'}\\
   {\tt WORDS('')} & $\rightarrow$ & {\tt '0'}
\end{tabular}
\end{quote}




\heading{XRANGE([{\it start}][,{\it end}])}{\rexxfunc}

Returns a string that consists of all the characters from {\it start}
through {\it end}, inclusive. The default value for character {\it
start} is {\tt '00'x}, while the default value for character {\it end}
is {\tt 'ff'x}.  Without any parameters, the whole characterset in
``alphabetic'' order is returned. Note that the actual representation
of the output from {\tt XRANGE()} depends on the character set used by
your computer.

If the value of {\it start} is larger than the value of {\it end}, the
output will wrap around from {\tt 'ff'x} to {\tt '00'x}. If {\it
start} or {\it end} is not a string containing exactly one character,
an error is reported.

\begin{quote}
\begin{tabular}{lll}
   {\tt XRANGE('A', 'J')} & $\rightarrow$ & {\tt 'ABCDEFGHIJ'}\\
   {\tt XRANGE('FC'x)} & $\rightarrow$ & {\tt 'FCFDFEFF'x}\\
   {\tt XRANGE(, '05'x)} & $\rightarrow$ & {\tt '000102030405'x}\\
   {\tt XRANGE('FD'x, '04'x)} & $\rightarrow$ & {\tt 'FDFEFF0001020304'x}
\end{tabular}
\end{quote}



\heading{X2B({\it hexstring})}{\rexxfunc}

Translate {\it hexstring} to a binary string. Each hexadecimal digits
in {\it hexstring} will be translated to four binary digits in the
result. There will be no blanks in the result. 



\heading{X2C({\it hexstring})}{\rexxfunc}

Returns the (packed) string representation of {\it hexstring}.  The
{\it hexstring} will be converted bytewise, and blanks may optionally
be inserted into the {\it hexstring} between pairs or hexadecimal
digits, to divide the number into groups and improve readability. All
groups must have an even number of hexadecimal digits, except the
first group. If the first group has an odd number of hexadecimal
digits, it is padded with an extra leading zero before conversion.

\begin{quote}
\begin{tabular}{lll}
   {\tt X2C('')} & $\rightarrow$ & {\tt ''}\\
   {\tt X2C('466f6f 426172')} & $\rightarrow$ & {\tt 'FooBar'}\\
   {\tt X2C('46  6f  6f')} & $\rightarrow$ & {\tt 'Foo'}
\end{tabular}
\end{quote}




\heading{X2D({\it hexstring}[,{\it length}])}{\rexxfunc}

Returns a whole number that is the decimal representation of {\it
hexstring}. If {\it length} is specified, then {\it hexstring} is
interpreted as a two's complement hexadecimal number consisting of the {\it
number} rightmost hexadecimal numerals in {\it hexstring}. If {\it
hexstring} is shorter than {\it number}, it is padded to the left with
{\sc NUL} characters (that is: {\tt '00'x}).

If {\it length} is not specified, {\it hexstring} will always be
interpreted as an unsigned number. Else, it is interpreted as an
signed number, and the leftmost bit in {\it hexstring} decides the
sign.

\begin{quote}
\begin{tabular}{lll}
   {\tt X2D('03 24')} & $\rightarrow$ & {\tt '792'}\\
   {\tt X2D('0310')} & $\rightarrow$ & {\tt '784'}\\
   {\tt X2D('ffff')} & $\rightarrow$ & {\tt '65535'}\\
   {\tt X2D('ffff', 5)} & $\rightarrow$ & {\tt '65535'}\\
   {\tt X2D('ffff', 4)} & $\rightarrow$ & {\tt '-1'}\\
   {\tt X2D('ff80', 3)} & $\rightarrow$ & {\tt '-128'}\\
   {\tt X2D('12345', 3)} & $\rightarrow$ & {\tt '837'}
\end{tabular}
\end{quote}



\section{Implementation specific documentation for {\regina}}


\subsection{Deviations from the Standard}

\begin{itemize}
\item
   For those builtin function where the last parameter can be omitted,
   {\regina} allows the last comma to be specified, even when the last
   parameter itself has been omitted. 

\item
   The error messages are slightly redefined in two ways. Firstly,
   some of the have a slightly more definite text, and secondly, some
   new error messages have been defined. 

\item
   The the environments available are described in chapter
   [not yet written].

\item parameter calling

\item stream I/O

\item conditions

\item national character sets

\item blanks

\item 
   Stacks have the following extra functionality: {\tt DROPBUF()},
   {\tt DESBUF()} and {\tt MAKEBUF()} and {\tt BUFTYPE()}.

\item random()

\item sourceline

\item time

\item character sets
\end{itemize}



\subsection{Interpreter Internal Debugging Functions}

\heading{ALLOCATED([{\it option}])}{\debug}

Returns the amount of dynamic storage allocated, measured in bytes.
This is the memory allocated by the {\tt malloc()} call, and does not
concern stack space or static variables.

As parameter it may take an {\it option}, which is one of the single
characters:
\begin{itemize}
\item[{\bf A}]
   This is the default value if you do not specify an option. It will
   return a string that is the number of bytes of dynamic memory
   currently allocated by the interpreter.

\item[{\bf C}]
   Returns a number that is the number of bytes of dynamic memory that
   is currently in use (i.e.~not leaked).

\item[{\bf L}]
   Returns the number of bytes of dynamic memory that is supposed to
   have been leaked.

\item[{\bf S}]
   Returns a string that is nicely formatted and contains all the
   other three options, with labels. The format of this string is:
   ``{\tt Memory: Allocated=XXX, Current=YYY, Leaked=ZZZ}''.
\end{itemize}
This function will only be available if the interpreter was compiled
with the {\tt TRACEMEM} preprocessor macro defined.


\heading{DUMPTREE()}{\debug}

Prints out the internal parse tree for the {\sc Rexx} program currently
being executed. This output is not very interesting unless you have
good knowlegde of the interpreter's internal structures.


\heading{DUMPVARS()}{\debug}

This routine dumps a list of all the variables currently defined.  It
also gives a lot of information which is rather uninteresting for most
users.


\heading{LISTLEAKED()}{\debug}

List out all memory that has leaked from the interpreter. As a return
value, the total memory memory that has been listed is returned. There
are several option to this function:
\begin{itemize}
\item[{\tt N}]
   Do not list anything, just calculate the memory.

\item[{\tt A}]
   List all memory allocations currently in use, not only that which
   has been marked as leaked.

\item[{\tt L}]
   Only list the memory that has been marked as leaked. This is the
   default option.
\end{itemize}


\heading{TRACEBACK()}{\debug}

Prints out a traceback. This is the same routine which is called when
the interpreter encounters an error. Nice for debugging, but not
really useful for any other purposes.




\subsection{{\sc Rexx} UNIX Interface Functions}


\heading{CHDIR({\it string})}{\unix}
Set {\it string} as current working directory.

A separate function is needed for this task in the current
implementation. But when commands are implemented using pipes/sockets
instead of the C function {\tt system()}, this will not be needed.
Then the {\sc Rexx} interpretor and its subprocesses have different current
directories.



\heading{GETENV({\it environmentvar})}{\unix}

Returns the named UNIX environment variable. If this variable is not
defined, a nullstring is returned.  It is not possible to use this
function to determine whether the variable was unset, or just set to
the nullstring.

This function is now obsolete, instead you should use:

\begin{quote}
   {\tt VALUE( {\it environmentvar},, 'SYSTEM' )}
\end{quote}


\heading{UNIXERROR({\it errorno})}{\unix}

This function returns the string associated with the {\tt errno}
error number that {\it errorno} specifies. When some UNIX interface
function returns an error, it really is a reference to an error message
which can be obtained through {\tt UNIXERROR}.

This function is just an interface to the {\tt strerror()} function
call in UNIX, and the actual error messages might differ with the
operating system.

This function is now obsolete, instead you should use:

\begin{quote}
   {\tt ERRORTEXT( 100 + {\it errorno} )}
\end{quote}


