QELEM


>>-QELEM-------------------------------------------------------><

queries the number of data stack elements that are in the most recently created data stack buffer (that is, in the buffer that was created by the MAKEBUF command). The number of elements is returned in the REXX special variable RC. When MAKEBUF has not been issued to create a buffer, QELEM returns the number 0 in the special variable RC, regardless of the number of elements on the data stack. Thus when QBUF returns 0, QELEM also returns 0.

The QELEM command can be issued from REXX execs that execute in both the TSO/E address space and in non-TSO/E address spaces.

QELEM only returns the number of elements in a buffer that was explicitly created using the MAKEBUF command. You can use QELEM to coordinate the use of MAKEBUF. Knowing how many elements are in a data stack buffer can also be useful before an exec issues the DROPBUF command, because DROPBUF removes the most recently created buffer and all elements in it.

The QELEM command returns the number of elements in the most recently created buffer. The QUEUED built-in function (see QUEUED) returns the total number of elements in the data stack, not including buffers.

After the QELEM command processes, the REXX special variable RC contains one of the following return codes:

Return code	Meaning
0	Either the MAKEBUF command has not been issued or the buffer that was most recently created by MAKEBUF contains no elements.
1	MAKEBUF has been issued and there is one element in the current buffer.
2	MAKEBUF has been issued and there are two elements in the current buffer.
3	MAKEBUF has been issued and there are three elements in the current buffer.
n	MAKEBUF has been issued and there are n elements in the current buffer.

Examples

If an exec creates a buffer on the data stack with the MAKEBUF command and then puts three elements on the data stack, the QELEM command returns the number 3.
```
"MAKEBUF"         /* buffer created */
PUSH one
PUSH two
PUSH three
"QELEM"
SAY 'The number of elements in the buffer is' RC  /* RC = 3 */
```
Suppose an exec creates a buffer on the data stack, puts two elements on the data stack, creates another buffer, and then puts one element on the data stack. If the exec issues the QELEM command, QELEM returns the number 1. The QUEUED function, however, which returns the total number of elements on the data stack, returns the number 3.
```
"MAKEBUF"         /* buffer created */
QUEUE one
PUSH two
"MAKEBUF"         /* second buffer created */
PUSH one
"QELEM"
SAY 'The number of elements in the most recent buffer is' RC /* 1 */
SAY 'The total number of elements is' QUEUED()  /* returns 3 */
```

To check whether a data stack buffer contains elements before you remove the buffer, use the result from QELEM and QBUF in an IF...THEN...ELSE instruction.

"MAKEBUF"
PUSH a
"QELEM"
NUMELEM = RC      /* Assigns value of RC to variable NUMELEM */
"QBUF"
NUMBUF = RC       /* Assigns value of RC to variable NUMBUF  */
IF (NUMELEM = 0) & (numbuf > 0) THEN
   "DROPBUF"
ELSE              /* Deletes most recently created buffer    */
   DO NUMELEM
      PULL elem
      SAY  elem
   END