The data stack is a repository for storing data for use by a REXX exec. You can place elements on the data stack using the PUSH and QUEUE instructions, and take elements off the data stack using the PULL instruction. You can also use TSO/E REXX commands to manipulate the data stack. For example, you can use the MAKEBUF command to create a buffer on the data stack and then add elements to the data stack. You can use the QELEM command to query how many elements are currently on the data stack above the most recently created buffer. TSO/E REXX commands describes the REXX commands for manipulating the data stack. z/OS TSO/E REXX User's Guide describes how to use the data stack and associated commands.

The data stack is associated with one or more language processor environments. The data stack is shared among all REXX execs that run within a specific language processor environment.

A data stack may or may not be available to REXX execs that run in a particular language processor environment. Whether a data stack is available depends on the setting of the NOSTKFL flag (see Flags and corresponding masks). When IRXINIT initializes an environment and the NOSTKFL flag is on, IRXINIT does not create a data stack or make a data stack available to the language processor environment. Execs that run in the environment cannot use a data stack.

Restriction: The NOSTKFL flag takes precedence over the NEWSTKFL flag. If the NOSTKFL flag is on, IRXINIT does not create a data stack or make a data stack available to the new environment regardless of the setting of the NEWSTKFL flag.

If the environment is the first environment on a chain, IRXINIT automatically initializes a new data stack regardless of the setting of the NEWSTKFL flag.

Restriction: If the NOSTKFL flag is on, IRXINIT does not initialize a data stack.

If the environment is not the first one on the chain, IRXINIT determines the setting of the NEWSTKFL flag. If the NEWSTKFL flag is off, IRXINIT does not create a new data stack for the new environment. The language processor environment shares the data stack that was most recently created for one of the parent environments. If the NEWSTKFL flag is on, IRXINIT creates a new data stack for the language processor environment. Any REXX execs that run in the new environment can access only the new data stack for this environment. Execs cannot access any data stacks that IRXINIT created for any parent environment on the chain.

Environments can only share data stacks that were initialized by environments that are higher on a chain.

If IRXINIT creates a data stack when it initializes an environment, the system deletes the data stack when that environment is terminated. The data stack is deleted at environment termination regardless of whether any elements are on the data stack. All elements on the data stack are lost.

Figure 1 shows three environments that are initialized on one chain. Each environment has its own data stack, that is, the environments do not share a data stack.

Figure 1. Separate data stacks for each environment

When environment 1 was initialized, it was the first environment on the chain. Therefore, a data stack was automatically created for environment 1. Any REXX execs that execute in environment 1 access the data stack associated with environment 1.

When environment 2 and environment 3 were initialized, the NEWSTKFL flag was set on, indicating that a data stack was to be created for the new environment. The data stack associated with each environment is separate from the stack for any of the other environments. If an exec executes, it executes in the most current environment (environment 3) and only has access to the data stack for environment 3.

Figure 2 shows two environments that are initialized on one chain. The two environments share one data stack.

Figure 2. Sharing of the data stack between environments

When environment 1 was initialized, it was the first environment on the chain. Therefore, a data stack was automatically created. When environment 2 was initialized, the NEWSTKFL flag was off indicating that a new data stack should not be created. Environment 2 shares the data stack that was created for environment 1. Any REXX execs that execute in either environment use the same data stack.

Suppose a third language processor environment was initialized and chained to environment 2. If the NEWSTKFL flag is off for the third environment, it would use the data stack that was most recently created on the chain. That is, it would use the data stack that was created when environment 1 was initialized. All three environments would share the same data stack.

As described, several language processor environments can share one data stack. On a single chain of environments, one environment can have its own data stack and other environments can share a data stack. Figure 3 shows three environments on one chain. When environment 1 was initialized, a data stack was automatically created because it is the first environment on the chain. Environment 2 was initialized with the NEWSTKFL flag on, which means a new data stack was created for environment 2. Environment 3 was initialized with the NEWSTKFL flag off, so it uses the data stack that was created for environment 2.

Figure 3. Separate data stack and sharing of a data stack

Environments can be created without having a data stack, that is, the NOSTKFL flag is on. Referring to Figure 3, suppose environment 2 was initialized with the NOSTKFL flag on, which means a new data stack was not created and the environment does not share the first environment's (environment 1) data stack. If environment 3 is initialized with the NOSTKFL flag off (meaning a data stack should be available to the environment), and the NEWSTKFL flag is off (meaning a new data stack is not created for the new environment), environment 3 shares the data stack created for environment 1.

When a data stack is shared between multiple language processor environments, any REXX execs that execute in any of the environments use the same data stack. This sharing can be useful for applications where a parent environment needs to share information with another environment that is lower on the environment chain. At other times, a particular exec may need to use a data stack that is not shared with any other execs that are executing on different language processor environments. TSO/E REXX provides the NEWSTACK command that creates a new data stack and that basically hides or isolates the original data stack. Suppose two language processor environments are initialized on one chain and the second environment shares the data stack with the first environment. If a REXX exec executes in the second environment, it shares the data stack with any execs that are running in the first environment. The exec in environment 2 may need to access its own data stack that is private. In the exec, you can use the NEWSTACK command to create a new data stack. The NEWSTACK command creates a new data stack and hides all previous data stacks that were originally accessible and all data that is on the original stacks. The original data stack is referred to as the primary stack. The new data stack that was created by the NEWSTACK command is known as the secondary stack. Secondary data stacks are private to the language processor environment in which they were created. That is, they are not shared between two different environments.

Figure 4 shows two language processor environments that share one primary data stack. When environment 2 was initialized, the NEWSTKFL flag was off indicating that it shares the data stack created for environment 1. When an exec was executing in environment 2, it issued the NEWSTACK command to create a secondary data stack. After NEWSTACK is issued, any data stack requests are only performed against the new secondary data stack. The primary stack is isolated from any execs executing in environment 2.

Figure 4. Creating a new data stack with the NEWSTACK command

If an exec executing in environment 1 issues the NEWSTACK command to create a secondary data stack, the secondary data stack is available only to REXX execs that execute in environment 1. Any execs that execute in environment 2 cannot access the new data stack created for environment 1.

TSO/E REXX also provides the DELSTACK command that you use to delete any secondary data stacks that were created using NEWSTACK. When the secondary data stack is no longer required, the exec can issue DELSTACK to delete the secondary stack. At this point, the primary data stack that is shared with environment 1 is accessible.

TSO/E REXX provides several other commands you can use for data stack functions. For example, an exec can use the QSTACK command to find out the number of data stacks that exist for the language processor environment. TSO/E REXX commands describes the different stack-oriented commands that TSO/E REXX provides, such as NEWSTACK and DELSTACK.