Functions supported for the data stack routine

The function to be performed by the data stack routine is passed in parameter 1. The valid functions are described below. The functions operate on the currently active data stack. For more information about each of the functions, see the individual descriptions of the corresponding data stack commands in this book.

PUSH

Adds an element to the top of the data stack.

PULL

Retrieves an element off the top of the data stack.

PULLEXTR

Bypasses the data stack and reads a string from the input stream. In TSO/E foreground, PULLEXTR reads from the terminal. In TSO/E background, PULLEXTR reads from SYSTSIN. In non-TSO/E address spaces, the PULLEXTR function reads from the input stream as defined by the INDD field in the module name table. The default is SYSTSIN.

PULLEXTR is useful if the data stack is empty or you want to bypass the data stack entirely. For example, suppose you use the PULL function and the data stack routine returns with a return code of 4, which indicates that the data stack is empty. You can then use the PULLEXTR function to read a string from the input stream.

QUEUE

Adds an element at the logical bottom of the data stack. If there is a buffer on the data stack, the element is placed immediately above the buffer.

QUEUED

Returns the number of elements on the data stack, not including buffers.

MAKEBUF

Places a buffer on the top of the data stack. The return code from the data stack routine is the number of the new buffer. The data stack initially contains one buffer (buffer 0), but MAKEBUF can be used to create additional buffers on the data stack. The first time MAKEBUF is issued for a data stack, the value 1 is returned.

DROPBUF n

Removes all elements from the data stack starting from the “n”th buffer. All elements that are removed are lost. If n is not specified, the last buffer that was created and all subsequent elements that were added are deleted.

For example, if MAKEBUF was issued six times (that is, the last return code from the MAKEBUF function was 6), and the command

DROPBUF 2

is issued, five buffers are deleted. These are buffers 2, 3, 4, 5, and 6.

DROPBUF 0 removes everything from the currently active data stack.

NEWSTACK

Creates a new data stack. The previously active data stack can no longer be accessed until a DELSTACK is issued.

DELSTACK

Deletes the currently active data stack. All elements on the data stack are lost. If the active data stack is the primary data stack (that is, only one data stack exists and a NEWSTACK was not issued), all elements on the data stack are deleted, but the data stack is still operational.

QSTACK

Returns the number of data stacks that are available to the running REXX exec.

QBUF

Returns the number of buffers on the active data stack. If the data stack contains no buffers, a 0 is returned.

QELEM

Returns the number of elements from the top of the data stack to the next buffer. If QBUF = 0, then QELEM = 0.

MARKTERM

Marks the top of the active data stack with the equivalent of a TSO/E terminal element, which is an element for the TSO/E input stack. The data stack now functions as if it were just initialized. The previous data stack elements cannot be accessed until a DROPTERM is issued. If you issue a MARKTERM, you must issue a corresponding DROPTERM to delete the terminal element that MARKTERM created.

MARKTERM is available only to calling programs to put a terminal element on the data stack. It is not available to REXX execs.

DROPTERM

Removes all data stack elements that were added after a MARKTERM was issued, including the terminal element created by MARKTERM. The data stack status is restored to the same status before the MARKTERM.

DROPTERM is available only to calling programs to remove a terminal element from the data stack. It is not available to REXX execs.