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

\chapter{The Stack}
\label{ch:stack}

\index{stack|(bold}
\begin{em}
   In this chapter, the stack and operations manipulating the stack
   are discussed. Since the stack is external to the {\rexx} language,
   there are large differences between implementations with respect to
   the stack. These differences are attempted described in the latter
   part of this chapter.

   Another goal of this chapter is to try to describe both the
   ``real'' standards and some of the most commonly used de facto
   standards related to stack operation. Where something is not a part
   of any defined standard, this is clearly labelled. Also, some
   liberties have been taken in order to create a coherent covabulary
   on a field where very little standardization has taken place.
\end{em}


\section{Background and history}

\index{queue|see {\rm stack}}
\index{external data queue|see {\rm stack}}
In the various definitions of {\rexx}, there are numerous references
to the ``stack'' (often called the ``external data queue'', or just
the ``queue''). It is a structure capable of storing information, but
it is not a part of the {\rexx} language itself.  Rather, it is a part
of the external environment supporting a {\rexx} implementation.

Originally, the references to the stack was introduced into {\rexx}
because of the strong binding between {\rexx} and IBM
mainframes\index{mainframes} in the early history of {\rexx}
\cite[page ??]{bmarks}. Most (all?)~of the operating systems for these
machines support a stack, and many of their script programming idioms
involve the stack. Therefore, it was quite natural to introduce an
interface to the stack into {\rexx}, and consequently today many of
the programming paradigms of {\rexx} involve a stack.

Unfortunately, this introduced an element of incompatibility into
{\rexx}, as the stack is not in general supported for other operating
systems. Consequently, {\rexx} implementors often must implement a
stack as well of the core {\rexx} interpreter. Since no authoritative
definition of the stack exists, considerable differences between
various implementations.  Ironically, although the stack was
introduced to help communication between separate programs, the
interpreter-specific implementations of stacks may actually be a
hindrence against compatibilty between different interpreters.

The stack may have ``seemed like a good idea at the time'', but in
hindsight, it was probably a bad move, since it made {\rexx} more
dependant on the host operating system and its interfaces. 


\section{General functionality of the stack}

This section describes the functionality generally available in
implementations of stacks. The basic functionality described here will
be complemented with information on specific implementations later.
Unless explicitly labelled otherwise, this functionality is available
in all standards treated in this documentation.


\subsection{Basic functionality}

Below is listed the general functionality of the stack, in order of
deceasing compatibility. I.e.~the functionality listed first is more
likely to be a part of all implementations than the ones listed at the
end of the list. 

\begin{itemize}
\item
   The stack is a datastructure, which strings can either be inserted
   into or extracted from. The strings in the stack are stored in a
   linear order. Extraction and insertion works at a granularity of a
   complete string, i.e.~it is not possible to insert or extract parts
   of string.

\item
   The stack has two ends: a top and a bottom.  New strings can be
   inserted into the stack in both ends, but strings can
   only be extracted from the top of the stack.

\item 
   There exists a way of counting the number of strings currently stored
   in the stack.
\end{itemize}

A stack is often compared with the pile of plates you often find in
cantinas. It allows you to either add new plates at the top of the
pile or take old plates from the top. When a plate is taken from the
pile, it will be the most recently plate (that is still present) added
to the pile. Stackoperating in {\rexx} work the same way, although
there also allow ``plates'' to be added to the bottom of the pile.

\begin{itemize}
\item 
   There might be an implementation-specific limit on the length and
   number of strings stored in the stack. Ideally, the maximum length
   will be fairly large, at least 2**16, although some implementations
   are likely to enforce shorter limits.  Similarly, there might be a
   limit on the number of strings that can be simultaneously stored in
   the stack. Ideally, there should be no such limit.

   Is is natural that there are limits imposed on the amount of memory
   occupied by the strings in the stack. Some implementations are
   likely to reserve a fixed (but perhaps configurable) amount of
   memory for this purpose while others can dynamically resize the
   stack as long as enough memory is available.

\item
   Some implementations might restrict the set of characters allowed
   in strings in the stack, although ideally, all characters should be
   allowed, even characters normally used for end-of-line or
   end-of-string.
\end{itemize}

This documentation use the term ``string'', while ``line'' is in
common use elsewhere. The term is used because the strings in the
stack are not inherently interpreted as lines (having an implied
end-of-line\index{end-of-line}), only as a string.

Note that the stack itself is not a part of {\rexx}, only the parts
which interface to the stack.

\begin{example}[Using the stack to transfer parameters]
\label{exam:stackarg}
This is a common {\rexx} idiom used in several situations for
special parameter passing. The following code illustrates its use:

\begin{verbatim}
   do i=1 to 10              /* for each parameter string        */
      queue string.1         /* put the string on the stack      */
      end
   call subrout 10           /* call the subroutine              */
   exit 

   subrout: procedure        /* the definition of the subroutine */
      do j=1 to arg(1)       /* for each parameter passed        */
         parse pull line.j   /* retrieve the parameter           */
         end
      ...                    /* do something with the parameters */
      return
\end{verbatim}
In this example, ten parameter strings are transferred to the
subroutine {\tt SUBROUT}. The parameters are stored in the stack, and
only the number of parameters are transferred as a ``real'' argument. 

There are several advantages: first, one avoids problems related to
exposing variable names. Since the data is stored on the stack, there
is no need to refer to the variable names and bind the variables in
the subroutine to variables in the caller routine. In TRL1, indirect
references to variables in\/ {\tt PROCEDURE EXPOSE}\ttindex{PROCEDURE
EXPOSE} is illegal, and this method circumvent the problem.

Two other ways around this problem is to use\/ {\tt
INTERPRET}\ttindex{INTERPRET} for the\/ {\tt PROCEDURE EXPOSE}
instruction in order to dynamically determine which variables to
expose; or to use the\/ {\tt VALUE()}\ttindex{VALUE()} built-in
function (with its two first parameters).  The former is incompatible
with TRL2, while the latter is incompatible with TRL1.  Using the
stack can solve the problem in a fashion compatible with both
standards.  Anyway, if the called routine is an external routine, then
exposing does not work, so using the stack to transfer values may be
the only solution.

Another advantage of this idiom; TRL only requires implementations to
support 10 parameters for subroutines. Although there are no reasons
why an implementation should set a limit for the number of parameters
a routine can get, you should use another mechanism than arguments
when the number of strings is greater than 10. Using the stack fixes
this.
\end{example}




\subsection{LIFO and FIFO stack operations}

\index{last-in-first-out|see {\rm LIFO}}
\index{first-in-first-out|see {\rm FIFO}}
As already mentioned, the stack is a linear list of strings.
Obviously, this list has two ends. Strings can only be extracted from
one end, while strings can be added to both ends. 

If a set of new strings are added to the same end as they are later
extracted from, the strings will be extraced in the reversed order
with respect to the order in which they were added. This is called
stacking ``LIFO''\index{FIFO}, which means ``last-in-first-out'',
meaning that the last string stacked, will be the first string extracted,
i.e.~reversal of the order.
%(see \cite[Mat 20\,:\,16]{bible})

Similarily, when a set of strings are stacked in the end opposite to
the end which they are later extracted from, they will be extracted in
the same order in which they were stacked. This is referred to as
``FIFO''\index{FIFO} stacking, meaning ``first-in-first-out''.

The FIFO method of stacking is also sometimes referred to as
``queueing'', while the LIFO method is sometimes referred to as
``stacking'' or ``pushing''. 


\subsection{Using multiple buffers in the stack}

\index{buffer|(bold}
\begin{em} 
   The concept of buffers and everything directly related to buffers
   lay without the domain of standard {\rexx}. Thus, this section
   describes a de facto standard.
\end{em}

Some implementations support ``buffers'', which are a means of
focussing on a part of the stack. When creating a new buffer, the old
contents of the stack is somewhat insulated from the effects of
stack operations. When the buffer is removed, the state of the old
buffer i restored, to some extent: Whenever a string is read from the
stack, and the topmost buffer on the stack is empty, then that buffer
will be destroyed. Consequently, if this situation has arisen,
dropping buffers will not restore the state of the stack before the
buffer was created.

The functionality of buffers, and their effect on other stack
operations may differ considerably between implementations.

Whenever a queuing operations is performed (e.g.~by the {\tt QUEUE}
instruction), then the new string is inserted into the bottom of the
topmost buffer, not the bottom of the stack. This is the same if the
stack has no buffers, but else, the outcome of the queuing operation
can be very different.

\index{CMS|see {\rm mainframe}}
With IBM mainframe operating systems like CMS\index{mainframe}, buffers
can be inserted on the top of the stack. To perform buffer operations,
operating system commands are used. It may be instructional to list
the buffer operations of CMS:

\begin{description}
\item[{\tt DESBUF}]\index{DESBUF@{\ptt DESBUF}}
   removes all strings and buffers from the stack, and leaves the
   stack clean and empty. It is often used instead of repeated calls
   to {\tt DROPBUF}\index{DROPBUF@{\ptt DROPBUF}}. It always returns
   the value zero.

\item[{\tt DROPBUF}]\index{DROPBUF@{\ptt DROPBUF}}
   removes zero or more buffers from the stack. It takes one parameter
   which can be omitted, and which must be an integer position if
   specified, and is the assigned number of the bottommust buffer to
   be removed, i.e.~that buffer and all buffers above it (and of
   course, all the strings in these buffers) are to be removed. If the
   parameter is not specified, only the topmost buffer is removed.
   The return valued is always zero, unless an error occurred.

\item[{\tt MAKEBUF}]\index{MAKEBUF@{\ptt MAKEBUF}}
   makes a new buffer on the stack, starting at the current top of the
   stack. The return code (as stored in the special variable {\tt
   RC})\index{RC@{\ptt RC}}\index{variable!special} is the number of
   buffers currently on the stack after the new buffer has been added.
   Obviously, this will be a positive integer.  This program takes no
   parameters.
\end{description}

One might regard a buffer as a sort of bookmark, which is inserted
into the stack, so that a subsequent {\tt DROPBUF} command can remove
the stack down to a particular such bookmark.

When such a mark is located on the top of the stack, and a {\tt PULL}
instruction is executed, the buffer mark is implicitly desctructed
when the {\tt PULL} instruction reads the string below the buffer mark.
This is to say that a buffer can be destroyed by either a {\tt DESBUF}
command, a {\tt DROPBUF} command, or a read from the stack (by either
the {\tt PULL} or {\tt PARSE PULL} instructions).


\subsection{The zeroth buffer}

\index{zeroth buffer}
Normally, data pushed on the stack is added to the top of the stack.
When a stack contains only one buffer, the strings in that buffer are
the strings stored above that buffer-mark. The strings below it are
not part of the first buffer; instead, they are said to belong to the
zeroth buffer.

Thus, all strings from the bottom of the stack, up till the first
buffer mark (or the top of the stack if no buffers exist) is said to
be the strings in the zeroth buffer. However, note that the zeroth
buffer is only defined implicitly. Thus, it can not really be removed
by calling {\tt DROP}; only the strings in the zeroth buffer are
removed. Afterwards, the zeroth buffer will still contain all strings
at the bottom of the stack, up till the first buffer
mark\index{buffer!mark} (if existing).

\begin{example}[Process all strings in the stack]
This is a common {\rexx} idiom, where a loop iterates over all the
strings currently in the stack, but otherwise leave the stack
untouched. Supposing the routine\/ {\tt PROCESS()} exists, and do to
processing with its parameter and return the processed string:

\begin{verbatim}
   do i=1 to 5                /* just to fill the stack      */
      push 'line #' i
      end

   do queued()                /* foreach line in the stack   */
      parse pull line         /* fetch the line              */
      queue process(line)     /* put back the processed line */
      end
\end{verbatim}

Here, it is important to use\/ {\tt QUEUE}\ttindex{QUEUE} to put the
strings back into the stack, not\/ {\tt PUSH}\ttindex{PUSH}, else the
loop will iterate the correct number of times, but only operate on the
same data string. It is also important that the stack does not contain
any buffers. Since\/ {\tt QUEUE} will insert into the bottom of the
topmost buffer, the loop would iterate the correct number of times,
but only on a part of the stack. Thus, the topmost part of the strings
in the stack would be processed multiple times.
\end{example}


\begin{example}[How to empty the stack]
The following short example shows how you can most easily empty the
stack:
\begin{verbatim}
   do i=1 to 5               /* Just to fill the stack */
      push 'line #' i
      end

   do queued()               /* For each line in the stack */
      pull                   /* Remove the line from the stack */
      end
\end{verbatim}
This is trivially simple, but there are several interesting and suptle
notes to make about this example. First, if the number of strings in the
stack is likely to change, due to some external process, then the\/ {\tt
DO}\index{DO@{\ptt DO}} clause should perhaps better be written as:
\begin{verbatim}
   do i=1 to 5               /* Just to file the stack */
      push 'line #' i
      end

   do while queued()>0       /* While the stack is not empty */
      pull                   /* Remove a line from the stack */
      end      
\end{verbatim}
This will in general mean more work for the interpreter, as it is now
required to check the number of strings in the stack for each
iteration, while for the previous code fragment, the number of strings
is only checked once. Another point is that this might not remove all
buffers\index{buffer} from the stack. Suppose the zeroth
buffer\index{zeroth buffer} is empty, i.e.~there exists an buffer
which was put on the stack when the stack was empty.  This buffer is
removed in any of the following situations: calling {\tt
DESBUF}\index{DESBUF@{\ptt DESBUF}}, calling {\tt
DROPBUF}\index{DROPBUF@{\ptt DROPBUF}} (sometimes), or reading a
string below the buffer mark. Since there are no strings below the
buffer mark, pulling a string from the stack would make the
interpreter read from the keyboard, and hang the interpreter.

Thus, the only ``safe'' way to remove the string and buffers from the
stack, without side effects, is to call\/ {\tt DESBUF} or\/ {\tt DROPBUF}.
On the other hand, if you only want to make sure that there are no
strings in the buffer, the method described here is more suitable,
since it is far more compatible (although possibly not so efficient).
But anyway, buffers are not a compatible construct, so it does not
matter so much.
\end{example}
\index{buffer|)}


\subsection{Creating new stacks}

\index{stack!multiple}
\begin{em}
   The description of multiple stack operations in this section, is
   not part of standard {\rexx}. Thus, this section describes a de
   facto standard and you may find that few implementations support
   these operations.
\end{em}

Just as the operations described above let the {\rexx} programmer use
multiple buffers within one stack, there exists another set of
operations which let the programmer create multiple stacks. There is
really nothing fancy about this, except that a command will swap the
stack the interpreter correctly uses with another stack.

To the interpreter this is really equivalent to a situation where a
command empties the current stack, and sets up a new stack. When one
stack is empty, and the {\rexx} program tries to read from the stack,
the request will not ``overflow'' to the previous stack (as requests
to an empty buffer ``overflows'' to the previous buffer). Thus, the
use of multiple stacks has even less direct inpact on {\rexx}
interpreters than multiple buffers. 

Here, it is instructive to list the commands operating 
multiple stacks that exists. This list has been taken from the
MVS\index{MVS} environment, according to \cite{rexxsaa}.
\begin{description}
\item[{\tt DELSTACK}]\index{DELSTACK@{\ptt DELSTACK}}
   is used to remove the most currently stack, and make the most
   recent of the saved stacks the current stack. When there are no
   saved stacks, the current stack is emptied. 

\item[{\tt NEWSTACK}]\index{NEWSTACK@{\ptt NEWSTACK}}
   creates a new stack, which becomes the current stack. The old
   current stack is put on the top of the list of saved stacks, and
   can be retrieved as the current stack by a subsequent {\tt
   DELSTACK}. 

\item[{\tt QBUF}]\index{QBUF@{\ptt QBUF}}
   counts the number of buffers in the current stack, and returns that
   number as the return value. A {\rexx} program starting this command
   can retrieve this value as the special variable {\tt
   RC}\index{special variable!{\tt RC}}

\item[{\tt QELEM}]\index{QELEM@{\ptt QELEM}}
   counts the number of strings (i.e.~elements) in the current stack,
   and returns that value as the return value of the command. This
   value can be retrieved in {\rexx} as the special variable {\tt
   RC}\index{special variable!{\tt RC}}. This operation is equivalent
   to the {\tt QUEUED()}\index{QUEUED()@{\ptt QUEUED()}} built-in
   function in {\rexx}; it has been probably included for the benefit
   of other script languages that have less functionality than {\rexx}.

\item[{\tt QSTACK}]\index{QSTACK@{\ptt QSTACK}}
   counts the number of stacks (including the current stack) and
   returns the value as the return value from the command. This number
   can be retrieved in {\rexx} as the special variable {\tt
   RC}.\index{special variable!{\tt RC}}
\end{description}

One can regard multiple buffers and stacks as two ways of insulating
the stack; where multiple stacks are a deeper and more insulating
method than buffers. Note that each stack can contain multiple
buffers, while a buffer can not contain any stacks. The term ``hard
buffers'' has been used about multiple stacks, as opposed to normal
buffers, which are sometimes called ``soft buffers''.

Also note that neither multiple stacks nor buffers are part of
standard {\rexx}, so you might come across implementations that
support only multiple stacks, only buffers, or even none of them. 


\begin{example}[Counting the number of buffers]
In\index{buffer} order to count the number of buffers on the stack,
the following method can be used (\/{\regina} syntax has been used for
buffer handling). This method is equivalent to the {\tt QBUF} command
described above. 
\begin{verbatim} 
   buffers = makebuf() - 1
   call dropbuf
\end{verbatim}
This will store the number of buffers in the stack in the variable
{\tt buffers}. However, just as for the other examples using buffers,
this example also suffers from the fact that buffer handling is
fairly non-standard. Thus, you will have to adapt the code to whatever
system you want to use.
\end{example}





\section{The interface between {\rexx} and the stack}

As defined in TRL, the interface to the stack consists of the {\tt
PARSE PULL}\index{PARSE@{\ptt PARSE}}\refer{inst:parse}, {\tt
PULL}\index{PULL@{\ptt PULL}}\refer{inst:pull}, {\tt
PUSH}\index{PUSH@{\ptt PUSH}}\refer{inst:push}, and {\tt
QUEUE}\index{QUEUE@{\ptt QUEUE}}\refer{inst:queue} instructions; and
the {\tt QUEUED()}\index{QUEUED()@{\ptt QUEUED()}}\refer{bif:queued}
built-in function.

There exists a binary interface to the stack in SAA, see the chapter
on the SAA API\index{SAA API} interface\refer{ch:saaapi} for more
information. This interface consists of the {\tt RXMSQ}\ttindex{RXMSQ}
exit handler \refer{saa:rxmsq} and the {\tt QUENAME}\ttindex{QUENAME}
value of the {\tt RXSHV\_PRIV}\ttindex{RXSHV\protect\_PRIV} request of
the {\tt RexxVariablePool()}\ttindex{RexxVariablePool()} function of
the variable pool interface\refer{sect:varpool}.



\section{Strategies for implementing stacks}

As mentioned, stacks are rarely a part of the operating system.
Therefore, under most operating systems, {\rexx} interpreters have to
implement their own stacks. There are several strategies for doing
this, some which are listed below.

\begin{description}
\item[In the operating system.]\index{operating system}
   This is of course ``the right way'' to do it. However, it requires
   that the definition of the operating system is such that stacks are
   supported. Currently, only IBM mainframe-based\index{mainframes}
   systems support stack, together with a few other systems that have
   included stacks as a consequence of making {\rexx} a main scripting
   language (Amiga\index{Amiga} and OS/2\index{OS/2} come to mind).

\item[As a device driver.]\index{device driver}
   This is really just a variation of making the stack a part of the
   operating system. However, in some systems, drivers can be added
   very easily to the system. Drivers are often filesystem-based, in
   which case driver-based stack operations must operate on a file or
   pseudo-file. But for some systems, adding a driver requires much
   more profound changes, reconfiguration, and often system
   privileges. In all cases, drivers are likely to be very system
   specific.

\item[As a daemon.]\index{daemon}
   A ``daemon'' is background process that does some housekeeping
   service, e.g.~handling mail from remote systems. Implementing a
   stack as a daemon is only slightly simpler than using a driver, but
   the main idea is the same for both approaches.

\item[In the interpreter.]
   Using this approach, the stack is built into the interpreter as a
   sort of extension. This is often the simplest way, since it require
   very little coordination with other programs during run-time.  The
   main problem is that the stack becomes private to the interpreter,
   so two interpreters can not use the same stack; not even if they
   are two invocations of the same interpreter.
\end{description}

These items are listed in the order of how closely they are coupled to
the operating system: the first items are very closely, while the last
items are lousely coupled. The more closely coupled the implementation
of a stack is coupled to the operating system, the better is the
chance that several interpreters on the same system can communicate in
a compatible way, using the stack.

There is room for several hybrid solutions, based on the four
fundamental approaches. For instance, a built-in stack can also act as
a daemon.

\begin{example}[Commands takes input from the stack]
\label{ex:cominp}
In\index{command} example \ref{exam:stackarg}, the routine that is called
takes its arguments from the stack.  Similarily, commands to an
external environment can get their arguments in the same way. Here is
an example of how to do it:
\begin{verbatim}
   queue 'anonymous'               /* the username */
   queue 'user@node'               /* the password */
   queue 'dir'                     /* first command */
   queue 'exit'                    /* second command */
   address command 'FTP flipper.pvv.unit.no'
\end{verbatim}
Although this is very convenient in some situations, there is also
considerable disadvantages with this method: There is no real
interactive communication between the interpreter and the command;
i.e.~all input ment for the command must be set up before the command
itself is invoked. Consequently, if one of the input lines to the
command provokes an error, there is very little error handling
facility. Commonly, such an error might start a cascade of errors, as
the remaining input lines are likely to be invalid, or even be
interpreted in a context different from what they were intended.

As with all commands involving the stack, it is important to push or
queue the correct order.

Using this technique, a program can ``fool'' a command to do almost
anything, by storing the correct input on the stack. However, there is
a big disadvantage: Since the stack is implementation-dependent, it is
not certain that a command will take its input from the stack. For
some systems, this is the default, while for other systems, this is
only possible through some explicit action. Some systems might not
even allow commands to take their input from the stack at all. 
\end{example}


\begin{example}[``Execing'' commands]
Many\index{command} script programming languages can only execute
commands while still running, or at most start a new command
immediately after the termination (like the {\tt
exec()}\index{exec()@{\tt exec()}} system call in Unix\index{Unix}).
However, the stack can be used on some systems to set up the system to
execute one or more commands after the current script terminates. Here
is an example:
\begin{verbatim}
   push 'ls'         /* finally execute 'ls' */
   push 'who'        /* then execute 'who'   */
   push 'pwd'        /* first execute 'pwd'  */
   exit 0
\end{verbatim}
Supposing that the system reads its commands from the stack if the
stack is not empty, then this script will terminate after having set
up the stack so that the three commands\/ {\tt pwd}, {\tt who} and\/
{\tt ls} will be run in that sequence. Note the order, if\/ {\tt
QUEUE} had been used, the order would be the opposite, which is
perhaps more intuitive (assuming the topmost buffer is empty).

As with example \ref{ex:cominp}, this too is only relevant for some
systems, thus is not very compatible, and you should be careful when
using it. It also suffers from the lack of interactivity, error
handling, and the importance of the order in which the strings are
pushed or queued. For all practical reasons, this is just a special
case of example \ref{ex:cominp}.

Using the stack to ``leave behind'' command names and input only works
for systems where command interpreters and commands reads their input
from the stack. This is in general true for IBM mainframe systems, but
very few other systems\index{mainframe}.
\end{example}




\section{Specific implementations of stacks}

Below is listed implementation-specific documentation, with respect to
stacks, for some interpreters. 


\subsection{Implementation of the stack in {\regina} {\ReginaVersion}}

\index{Regina@{{\regina}}|(}
In {\regina}, the stack is implemented as an intergral, private part
of the interpreter. The advantage of this is that stack operations are
very fast. On the other hand, it means that two interpreters running
on the same machine does not use the same stack. Further, it means
that a program can not on its own initiative communicate with the
stack; such piping must be set up by the interpreter at the invocation
time of the program.

Whenever the {\rexx} programmer wants to execute a
command\index{command} and let that command either flush the output to
the stack, or read its input from the stack, this has to be arranged
by the interpreter itself.  In {\regina} this is normally done by
prepending or appending certain terms to the command to be executed.
Consider the following command clauses for {\regina}:
\begin{verbatim}
   'ls >LIFO'
   'who >FIFO'
   'LIFO> wc'
   'ps'
   'LIFO> sort >FIFO'
\end{verbatim}
\index{>LIFO@{\ptt LIFO}|see {\tt LIFO>}}
\index{>FIFO@{\ptt FIFO}|see {\tt FIFO>}}
\index{LIFO>@{\ptt LIFO}}
\index{FIFO>@{\ptt FIFO}}
\index{piping|see redirection}
For all these commands, the ``piping''\index{redirection} terms are
stripped off the command string before the command is sent to the
command interpreter of the operating system. Thus, the command
interpreter only sees the commands {\tt ls}, {\tt who}, {\tt
wc}, and {\tt sort}. The terms stripped off, are used as
indicators of how the input and output is to be coupled with the
stack. Note that it is important not to confuse the redirection of
output to the stack and input from the stack in {\regina} with the
redirection of the Unix shells. The two can be mixed in command lines,
but are still two different concepts. 

The first command will execute the {\tt ls} command, and redirect the
output from it to the stack in a LIFO\index{LIFO} fashion. The second
executes the command {\tt who} and redirects the output to the stack
to, but in a FIFO fashion. The third command executes the {\tt wc},
but lets the standard input of that command come from the stack.
Actually, it is irrelevant whether {\tt FIFO>}\index{FIFO>} or {\tt
LIFO>} is used for input; the strings are read from the top of the
stack in both cases.  The fourth command is a plain {\tt ps} command
without any redirection to or from the stack. The last command
executes the {\tt sort} program and lets it read its input from the
stack, and redirect the output to the stack.

{\regina} allows a command to take both an input and an output
``redirection'' to a stack, as showed in the last example above.
However, it also garantees that the output is not available in the
stack before the command has terminated. The output from the command
is stored in a temporary stack, and flushed to the ordinary stack
after the command is terminated. Thus, the command will not start to
read its own output.

Note that this temporary buffering of command output is the default
behavior, which might be set up to something different at your site.
In addition, you can change it through the {\tt
OPTIONS}\index{OPTIONS@{\ptt OPTIONS}} instruction, by using either
{\tt FLUSHSTACK}\index{FLUSHSTACK@{\ptt FLUSHSTACK}} or {\tt
BUFFERSTACK}\index{BUFFERSTACK@{\ptt BUFFERSTACK}} as
``parameters''\refer{ext:buffer}.

Furthermore, {\regina} supports the standard TRL {\rexx} stack
interface functionality, like {\tt PARSE PULL}\index{PARSE@{\ptt
PARSE}}, {\tt PULL}\index{PULL@{\ptt PULL}}, {\tt
QUEUE}\index{QUEUE@{\ptt QUEUE}}, {\tt PUSH}\index{PUSH@{\ptt PUSH}},
the {\tt QUEUED()}\index{QUEUED()@{\ptt QUEUED()}} built-in function,
and the SAA API\index{SAA API} stack interface. In addition, there are
a few extra built-in functions, which are supposed to provide
compatibility with other {\rexx} implementations. These are:

Again, note the difference between {\regina}'s redirection and Unix
redirection. In {\regina}, only the terms {\tt LIFO>} and {\tt FIFO>}
(when first in the command string), and the terms {\tt >LIFO} and {\tt
>FIFO} (when last in the command string), will be interpreted as
redirection directives. These terms will be stripped off the command
string.  All other redirection directives will be left untouched. If
you should happen to need to redirect output from a Unix command to
the file {\tt FIFO} or {\tt LIFO}, then you can append a space at the
end. That will make {\regina} ignore the redirection term and the
space is ignored by Unix.

Note that this particular form of redirection of command input and
output will most probably disappear in future versions of {\regina},
where it will probably be replaced by an extended {\tt ADDRESS}
instruction\index{ADDRESS@{\ptt ADDRESS}}.


\builtin{BUFTYPE()}

\index{BUFTYPE()@{\ptt BUFTYPE()}}
This function is used for displaying the contents of the stack. It
will display both the string and notify where the buffers are
displayed. It is ment for debugging, especially interactive, when you
need to obtain information about the contents of the stack. It always
returns the nullstring, and takes no parameters.

Here is an example of the output from calling {\tt BUFTYPE} (note that
the second and fourth buffers are empty):
\begin{samepage}
\begin{verbatim}
   ==> Lines: 4
   ==> Buffer: 3
   "fourth line pushed, in third buffer"
   ==> Buffer: 2
   ==> Buffer: 1
   "third line pushed, in first buffer"
   ==> Buffer: 0
   "second line pushed, in 'zeroth' buffer"
   "first line pushed, in 'zeroth' buffer"
   ==> End of Stack
\end{verbatim}
\end{samepage}

\begin{exbox}
   \exline{BUFTYPE()}{}{the nullstring, always}
\end{exbox}


\builtin{DESBUF()}

\index{DESBUF()@{\ptt DESBUF()}}
This function removes all buffers\index{buffer} on the stack, it is
really just a way of clearing the whole stack for buffers as well as
strings.  Functionally, it is equivalent to executing {\tt
DROPBUF}\index{DROPBUF@{\ptt DROPBUF}} with a parameter of {\tt 0}.
(Actually, this is a lie, since {\tt DROPBUF}\index{DROPBUF@{\ptt
DROPBUF}} is not able to take zero as a parameter.
Rather\markit{subtle}, it is equivalent to executing {\tt DROPBUF}
with {\tt 1} as parameter and then executing {\tt DROPBUF} without a
parameter, but this is a subtle point.) It will return the number of
buffers left on the stack after the function has been executed. This
should be {\tt 0} in all cases.

\begin{exbox}
   \exline{DESBUF()}{0}{always}
\end{exbox}



\builtin{DROPBUF([{\it number\/}])}

\index{DROPBUF()@{\ptt DROPBUF()}}
This function will remove zero or more buffers\index{buffer} from the
stack. Called without a parameter, it will remove the topmost buffer
from the stack, provided that there were at least one buffer in the
stack. If there were no buffers in the stack, it will remove all strings
in the stack, i.e.~remove the zeroth buffer\index{zeroth buffer}.

If the parameter {\it number\/} was specified, and the stack contains
a buffer with an assigned number equal to {\it number\/}, then that
buffer itself, and all strings and buffers above it on the stack will be
removed; but no strings or buffers below the numbered buffer will be
touched. If {\it number\/} refers to a buffer that does not exist in
the stack; no strings or buffers in the stack is touched. 

As an extra extension, in {\regina} the {\tt DROPBUF()} built-in
function can be given a non-positive integer as parameter. If the name
is negative then it will convert that number to its absolute value,
and remove that many buffers, counted from the top. This is
functionally equivalent to repeating {\tt DROPBUF()} without
parameters for so many times as the absolute value of the negative
number specifies. Note that using {\tt -0} as parameter is equivalent
to removing all strings and buffers in the stack, since {\tt -0} is
equivalent to normal {\tt 0}. The number is converted during
evaluation of parameters prior to the call to the {\tt DROPBUF()}
routine, so the signe is lost.

The value returned from this function is the number of buffers left on
the stack after the buffers to be deleted have been removed.
Obviously, this will be a non-negative integer. This too, deviates
from the behavior of the {\tt DROPBUF}\index{DROPBUF@{\ptt DROPBUF}}
command under CMS\index{CMS}, where zero is always returned.

\begin{exbox}
   \exline{DROPBUF(3)}{2}{remove buffer 3 and 4}
   \exline{DROPBUF(4)}{0}{no buffers on the stack}
   \exline{DROPBUF()}{4}{if there where 5 buffers} 
\end{exbox}


\builtin{MAKEBUF()}

\index{MAKEBUF()@{\ptt MAKEBUF()}}
Creates a new buffer on the stack, at the current top of the stack.
Each new buffer will be assigned a number; the first buffer being
assigned the number {\tt 1}. A new buffer will be assigned a number
which is one higher than the currently highest number of any buffer on
the stack. In practice, this means that the buffers are numbered, with
the bottommost having the number {\tt 1} and the topmost having a
number which value is identical to the number of buffers currently in
the stack.

The value returned from this function is the number assigned to the
newly created buffer. The assigned number will be one more than the
number of buffers already in the stack, so the numbers will be
``recycled''. Thus, the assigned numbers will not neccessarily be in
sequence. 

\begin{exbox}
   \exline{MAKEBUF()}{1}{if no buffers existed}
   \exline{MAKEBUF()}{6}{if 5 buffers existed}
\end{exbox}
\index{Regina@{{\regina}}|)}
\index{stack|)}
