7.2.1 Basic functionality
Below is listed the general functionality of the stack, in order
of decreasing 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.

·    The stack is a data structure, 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.

·    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.

·    There exists a way of counting the number of strings
  currently stored in the stack.

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. Stack operating in REXX work the same
way, although there also allow “plates” to be added to the bottom
of the pile.

·    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.

·    It 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 re-size the
  stack as long as enough memory is available.

·    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.

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), only as a string.

Note that the stack itself is not a part of REXX, only the parts
which interface to the stack.

Example: Using the stack to transfer parameters

This is a common REXX idiom used in several situations for special
parameter passing. The following code illustrates its use:

     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

In this example, ten parameter strings are transferred to the
subroutine 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 PROCEDURE EXPOSE is
illegal, and this method circumvent the problem.

Two other ways around this problem is to use INTERPRET for the
PROCEDURE EXPOSE instruction in order to dynamically determine
which variables to expose; or to use the 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.


 PREV   NEXT