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

SWAPSTAK()

This function creates and switches between multiple numbered stacks. Once a stack is made current by the SWAPSTAK() function, all native REXX and TSO/E emulation stack commands operate typically.

Syntax

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

Parameters

stack

Error text is returned if the operation is not successful. Otherwise, the current stack number is returned.

n

A desired stack number. You can specify any number between 0 and 231-1. If the specified stack does not exist, it is created. Although available memory limits the total number of stacks that an IMOD can maintain, large numbers of stacks (over 25, for example) compromise stack-switching efficiency.

NEW

Beginning with stack 0, examines each stack until one is found with 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 want 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 NEWSTACK and MAKEBUF markers, as placed by the NEWSTACK and MAKEBUF commands.
• The current stack setting is retained during the 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() can 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 number of the stack 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() never returns a stack that was not previously in never-used status The SWAPSTAK(NEW) operation itself changes the status of the stack to empty. To destroy a stack, use the DELETE argument. Doing so discards remaining records and returns the stack to never-used status.

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  */