The List Form of the STACK macro instruction

The list form of the STACK macro instruction builds and initializes a STACK parameter block (STPB), according to the operands you specify in the macro. The STACK parameter block indicates to the STACK service routine which functions you want performed.

In the list form of the macro instruction, only

STACK      MF=L

is required. When only STACK MF=L is specified, the STPB is zeroed. The other operands and their sublists are optional because they can be supplied by the execute form of the macro instruction.

Figure 1 shows the list form of the STACK macro instruction; each of the operands is explained following the figure.

Figure 1. The List Form of the STACK macro instruction

                       [ TERM=*                                   ]
                       [                                          ]
[symbol]     STACK     [ BARRIER= {*      }                       ]
                       [          {NONEST }                       ]
                       [                                          ]
                       [         {TOP    }                        ]
                       [ DELETE= {PROC   }                        ]
                       [         {ALL    }                        ]
                       [         {BARRIER}                        ]
                       [                                          ]
                       [ ENVIRON= {CREATE  }                      ]
                       [          {DESTROY }                      ]
                       [          {RESET   }                      ]
                       [                                          ]
                       [ INQUIRE= {ATTN }                         ]
                       [          {ERROR}                         ]
                       [          {TYPE }                         ]
                       [                                          ]
                       [                           {PROCN,PROMPT} ]
                       [ STORAGE=(element address, {PROCL,PROMPT} ]
                       [                           {SOURCE      })],MF=L
                       [                                          ]
                       [         { *                     }        ]
                       [ DATASET={ INDD=addr1,PROMPT,LIST}        ]
                       [         { MEMBER=addr3          }        ]
                       [         { OUTDD=addr2,CNTL,SEQ  }        ]
                       [         { CLOSE                 }        ]

TERM=*

adds a terminal element to the input stack.

Note: TERM=* is allowed by STACK to provide compatibility with existing modules when they are recompiled.

BARRIER=

creates a barrier element, which divides the input stack into substacks, on top of the input stack.

*: CLISTs and REXX execs on opposing sides of this barrier are nested. They are able to use command output trapping and can communicate through global variables. Command Processors can use routines IKJCT441 and IRXEXCOM to access variables on the opposing side of the barrier.
NONEST: CLISTs and REXX execs on opposing sides of the barrier are not nested. This type of barrier halts the effect of command output trapping and halts the use of the routines IKJCT441 and IRXEXCOM to access variables on the opposing side of the barrier. While CLIST global variables are not communicated across this barrier, CLISTs on top of this barrier can begin using global variables and communicate with further nested CLISTs through global variables.

Note: When stacking and removing barrier elements:

Only STACK DELETE=BARRIER or STACK ENVIRON=RESET can remove a barrier element.
If the application or Command Processor stacks a barrier element, the application or Command Processor must remove the barrier element when it is done using the task. Failure to remove the barrier element can result in miscommunication between the application that invoked your Command Processor and other Command Processors and applications that use barriers on the current input stack.

DELETE=

deletes an element or elements from the input stack. TOP, PROC, ALL, or BARRIER further defines the element to be deleted.

TOP: deletes the topmost element (the element most recently added to the input stack). If the top element is a barrier element, STACK DELETE=TOP is a no-operation instruction.
PROC: deletes the current procedure element from the input stack. If the top element is not a PROC element, deletes all elements down to, and including, the first PROC element.
ALL: deletes all elements, except the bottom or first element, from the input stack. If one or more barrier elements exist on the input stack, deletes all elements down to, but not including, the first barrier element.
BARRIER: deletes all elements down to, and including, the first barrier element.

ENVIRON=

specifies one of the following operations:

A new TSO/E I/O environment is to be created
An existing TSO/E I/O environment is to be destroyed
The current TSO/E I/O environment is to be reset.

A TSO/E I/O environment consists of the control blocks that describe the input and output sources used by the I/O service routines. These control blocks include the environment control table (ECT) and the input stack.

CREATE

specifies that a new TSO/E I/O environment is to be created. The STACK service routine creates a new environment using a model environment provided by your Command Processor. To create a new I/O environment, follow these steps:

Set the IOPLECT field in the input/output parameter list (IOPL) to the address of the ECT to be used as a model to create a new ECT. The IOPL is described in The Input/Output Parameter List. The ECT that you provide as the model is passed to your Command Processor in the Command Processor parameter list (CPPL). For more information on the CPPL, see Interfacing with the TSO/E service routines.
Invoke the STACK service routine, specifying the ENVIRON=CREATE operand.

When the STACK service routine returns control to your Command Processor, the STPBECTA field of the STACK parameter block (STPB) contains the address of the new ECT. The ECTIOWA field in the ECT contains the address of the newly-created stack. The STACK service routine initializes the first (bottom) element of the new stack. This bottom element is the same as the bottom element of the model stack.

Note:

If you create a TSO/E I/O environment, and if you want to run REXX execs in that environment, you must create a new REXX environment by calling IRXINIT. See z/OS TSO/E REXX Reference for information on calling IRXINIT. Similarly, before you terminate the new TSO/E environment, you must end the new REXX environment by calling IRXTERM.
The CREATE operand creates an ALTLIB environment in which only the system CLIST library (ddname SYSPROC) and possibly the system REXX library (ddname SYSEXEC, by default) are searched. The ALTLIB environment in the new TSO/E I/O environment is independent of the ALTLIB environment in the model environment.
When TSO/E is processing an authorized command, you cannot use an alternate ECT for command output trapping or data stack prompting.

DESTROY

specifies that an existing TSO/E I/O environment is to be destroyed. The environment to be destroyed must have been created by the ENVIRON=CREATE function. To destroy an existing I/O environment, follow these steps:

Set the IOPLECT field in the input/output parameter list (IOPL) to the address of the ECT associated with the environment to be destroyed. The IOPL is described in The Input/Output Parameter List.
Invoke the STACK service routine, specifying the ENVIRON=DESTROY operand.

Note:

You cannot destroy an I/O environment at one task level while another task is using the I/O environment, even at the task level that created the I/O environment. If you attempt to do so, the STACK service routine will issue abend code X'66D'.
When you destroy an I/O environment, the ECT address and the input stack address, ECTIOWA, must be the same as when the I/O environment was created. If you attempt to destroy an I/O environment when the addresses are not the same, the STACK service routine passes a return code of 76 to the application program.

RESET

specifies that all elements, including barrier elements, are to be removed from the input stack of the current environment. However, the first element on the input stack is not removed.

INQUIRE=

returns a code that indicates:

Whether there is a CLIST attention routine to run
Whether there is a CLIST error routine to run
The type of the topmost element on the input stack.

See Return Codes from STACK for the meaning of each of the return codes.

ATTN: returns a code that indicates whether a CLIST attention routine is present anywhere in the current substack.
ERROR: returns a code that indicates whether a CLIST error routine is present in the top element of the current substack.
TYPE: returns a code that indicates the type of the topmost element on the input stack.

STORAGE=element address

adds an in-storage element to the input stack. The element address is the address of the list source descriptor (LSD). The LSD is a control block, pointed to by the STACK parameter block, which describes the in-storage list. The LSD must reside below 16 MB in virtual storage. See Building the List Source Descriptor (LSD) for a description of the LSD.

The in-storage element must be further defined as a SOURCE, PROCN, or PROCL list. SOURCE is the default.

PROMPT: specifies prompting by commands within a command procedure. PROMPT is used with the keywords PROCN and PROCL, which specify that the element to be added to the input stack is a command procedure.
PROCN: The element to be added to the input stack is a command procedure and the NOLIST option has been specified.
PROCL: The element to be added to the input stack is a command procedure and the LIST option has been specified. Each line read from the command procedure is written to the terminal.
SOURCE: The element to be added to the input stack is an in-storage source data set.

MF=L

indicates that this is the list form of the macro instruction. This operand is required.

DATASET=

Expands the facilities of dataset I/O for TSO/E commands to include reading from a SYSIN data set and writing to a SYSOUT dataset. To use the dataset function, the input and output files passed to the STACK service routine must be preallocated, either by a previously issued ALLOCATE command, a command processor that invokes dynamic allocation, a DD statement specified in the logon procedure, or, in the background, a user-supplied DD statement.

*: specifies that STACK use the bottom element in the input stack for I/O operations. This operand is the functional equivalent of TERM=*.
INDD=addr1: specifies the input file name.
PROMPT: allows prompting if prompting is also allowed on the bottom element of the input stack.
LIST: lists the input from the input stream.
MEMBER=addr3: specifies an 8-character member name for a partitioned data set which was specified as the input file with the INDD operand.
OUTDD=addr2: specifies the output file name.
CNTL: The output line has its own control character.
CLOSE: closes the data control blocks (DCBs) of the input stack. These DCBs are created by the STACK service routine. Your program cannot modify the DCBs directly; you must invoke the STACK service routine to modify these control blocks.
SEQ: indicates to dataset I/O that sequence numbers should not be removed.

Note: INDD and OUTDD are only valid if the associated dataset element is the last element stacked on the TSO/E I/O stack. If any element such as a CLIST element, or elements from invoking the TSO/E service facility are stacked after the DATASET element, INDD and OUTDD will become incorrect. This will cause the I/O to be routed to the bottom element on the I/O stack. This is the functional equivalent of DATSET=*, or TERM=*, and refers to SYSTSIN and SYSTSPRT.