The REXX Stack

The REXX stack is implemented by a stack process, with which the
interpreter communicates by means of a socket. The PUSH, QUEUE, and PULL
instructions and the QUEUED() function all communicate with the stack
process.

If a stack exists, then the standalone program rxstack may be used to
stack or retrieve data. This can be used to communicate to rexx the
output of a command (for instance "ls -al | rxstack") or to input data
from rexx (for instance "rxstack -print > /tmp/file"). The invocation
syntax of this program is:

rxstack [-fifo|-lifo] [-print|-pop|-peek|-drop|-num|-string "data"]

The meaning of these flags is as follows:
   -fifo   stack in FIFO order (the default)
   -lifo   stack in LIFO order
   -print  empty the stack, outputting each item on standard output
   -pop    pop one item and output on standard output
   -peek   output the first item on standard output without deleting it
   -drop   discard one item
   -num    output the number of items currently stacked on standard
           output in decimal, followed by newline character
   -string interpret the next argument as a literal string to be stacked
If none of the above flags (except -fifo or -lifo) is specified, then
each line of standard input is stacked until an EOF is received.

Each stack item may contain arbitrary characters, including newline
characters, but when rxstack takes input from standard input, all
newline characters are taken to be item separators and are deleted
before each item is stacked. Similarly, when rxstack outputs stack items
each item is followed by a newline character.

The name of the socket used for communication is stored in the
environment variable RXSTACK. It is assumed that a stack exists if and
only if this variable exists. Multiple processes may share the same stack
but multiple users may not usually share one stack because the sockets
for each user are kept in a separate protected directory belonging to
that user.

When REXX is invoked, if no stack exists then one is created, and is
destroyed when REXX exits. If a stack exists then REXX uses that stack.

The program rxque may be used to create a stack process independently of
REXX (for instance, so that REXX need not create one on startup, or so
that stack data may persist across invocations of REXX). This is done
by the program rxque. It may be invoked in three different ways:

rxque
   starts a stack process in the background and outputs two environment
   variables to stdout in the format
   RXSTACK=<name> RXSTACKPROC=<number>
   where RXSTACKPROC is the process number of the stack, which must be
   killed when the stack is no longer needed. To avoid unwanted processes
   being left around when errors occur, rxque will terminate itself if it
   finds that its parent process no longer exists when it has been
   sleeping for five minutes without communication.
   
   This output can either be parsed by a controlling program or used
   directly by a shell, for instance by:
   eval `rxque`;export RXSTACK RXSTACKPROC

rxque -csh
   is similar to the above but outputs two setenv commands in a format
   acceptable for the c-shell, so that
   eval `rxque -csh`
   will set the environment variables correctly in the c-shell.

rxque <filename>
   starts a stack process in the background which uses <filename> as the
   communication socket. This file will be deleted if it exists, before
   the socket with that name is opened. The process number of the stack
   process will be output to stdout, followed by a newline.

For instance:
% eval `rxque -csh`
% ls -al | rxstack -lifo
% rxstack -num
45
% rxstack -print
[many lines deleted]
drwxr-xr-x 13 imc          1536 Oct 28 16:56 ..
drwx------  5 imc          1024 Oct 28 13:12 .
total 194
% kill $RXSTACKPROC
% unsetenv RXSTACK
% rxstack
RX Stack not found