SWAPSTAK()

CA-GSS Statements and Commands › GSS Extended Functions › IO Functions › Number, String, and Variable Functions › System Information Functions › SWAPSTAK()

SWAPSTAK()

Use the SWAPSTAK() function to create and switch between multiple numbered stacks. Once a stack is made current by the SWAPSTAK() function, all native REXX and TSO/E emulation stack commands operate normally.

Syntax

The SWAPSTAK() function has this syntax:

stack = SWAPSTAK([n|NEW|DELETE])

Arguments

The SWAPSTAK() function takes these arguments:

stack	Error text is returned if the operation is not successful. Otherwise, the current stack number is returned.
n	Desired stack number. You can specify any number between 0 and 231-1. If the specified stack does not exist, it is created. Although the total number of stacks that an IMOD can maintain is limited only by available memory, large numbers of stacks (over 25, for example) compromise stack-switching efficiency.
NEW	Beginning with stack 0, examines each stack until one is found that has a status of "never-used" (the status of a stack that has never been referenced, a stack that has been explicitly destroyed with a SWAPSTAK(DELETE) operation). This stack is then assigned a status of "empty" and it is made the current stack. This is useful for subroutines that desire a temporary workspace.
DELETE	Deletes the currently accessed stack and returns it to "never-used" status. Stack 0 becomes the current stack. If you delete stack 0, it is automatically recreated as an empty stack.

Usage Notes

When an IMOD task is first created, SWAPSTAK(0) is in effect.
Stacks created by SWAPSTAK() are complete stack structures and can contain both NEWSTACK and MAKEBUF markers, as placed by the NEWSTACK and MAKEBUF commands.
The current stack setting is retained during CALL and RETURN operations.
If the argument is omitted, the stack number is left unchanged and its current value is returned.
All stack functions except QUEUED() may operate on any stack by specifying its number as an argument. All other methods for operating on stacks that do not provide a way of specifying the stack's number can only be used if the stack has been made the current stack by use of SWAPSTAK().
There is a subtle but important difference between an empty stack and a never-used stack. An empty stack exists, but has no records. A never-used stack has no existence. Requesting a NEW stack with SWAPSTAK() will never return a stack that was not previously in never-used status (The SWAPSTAK(NEW) operation itself changes the stack's status to empty. If you want to destroy a stack, use the DELETE argument. This will both discard any remaining records and return the stack to never-used status.

Return Codes

The SWAPSTAK() function produces these return codes:

101	ARG 1 MISSING OR INVALID

Example

/* This code segment can be used to obtain a work stack */

ostack = swapstak(  )         /* Save current stack number      */
x      = swapstak('new')      /* Obtain new stack for workspace */
x      = swapstak('delete')   /* Delete workspace stack         */
x      = swapstak(ostack)     /* Restore original stack number  */

Tell Technical Publications how we can improve this information