$STACK (ObjectScript)
Synopsis
$STACK
$ST
Description
$STACK contains the number of context frames currently saved on the call stack for your process. You can also look at $STACK as the zero-based context level number of the currently executing context. Therefore, when an InterSystems IRIS job is started, before any contexts have been saved on the call stack, the value of $STACK is zero (0).
Each time a routine calls another routine with a DO command, the context of the currently executing routine is saved on the call stack and execution starts in the newly created context of the called routine. The called routine can, in turn, call another routine and so on. Each additional call causes another saved context to be placed on the call stack.
An XECUTE command and a user-defined function reference also establish a new execution context. A GOTO command does not.
As new contexts are created by DO commands, XECUTE commands, or user-defined function references, the value of $STACK is incremented. As contexts are exited with the QUIT command, previous context are restored from the call stack and the value of $STACK is decremented.
This special variable cannot be modified using the SET command. Attempting to do so results in a <SYNTAX> error.
$ESTACK is identical to $STACK, except that you can establish a $ESTACK level of 0 (zero) at any point by issuing a NEW $ESTACK command. You cannot NEW the $STACK special variable.
Error Handling
When an error occurs, all context information is immediately saved on your process error stack. This changes the value of $STACK. The context information is then accessible using the $STACK function until the value of $ECODE is cleared by an error handler. In other words, while the value of $ECODE is non-null, the $STACK function returns information about a context saved on the error stack rather than an active context at the same specified context level.
Context Levels from the Terminal Prompt
A routine that is invoked from a program starts at a different context level than a routine invoked from the Terminal prompt with a DO command. The DO command typed at the Terminal prompt causes a new context to be created. The following example shows the routine START invoked from a routine or from the Terminal prompt:
Consider the following routine:
START
; Display the context level and exit
WRITE !,"Context level in routine START is ",$STACK
QUIT
When you run START from a program, you see the following display:
Context level in routine START is 0
When you run START by issuing DO ^START at the Terminal prompt, you see the following display:
Context level in routine START is 1
Examples
The following example demonstrates how the value of $STACK is incremented as new contexts are create and decremented as contexts are exited.
The sample code is as follows:
STA
WRITE !,"Context level in routine STA = ",$STACK
DO A
WRITE !,"Context level after routine A = ",$STACK
QUIT
A
WRITE !,"Context level in routine A = ",$STACK
DO B
WRITE !, "Context level after routine B = ",$STACK
QUIT
B
WRITE !,"Context level in routine B = ",$STACK
XECUTE "WRITE !,""Context level in XECUTE = "",$STACK"
WRITE !,"Context level after XECUTE = ",$STACK
QUIT
A sample session using this code might run as follows:
USER>DO ^STA
Context level in routine STA = 1
Context level in routine A = 2
Context level in routine B = 3
Context level in XECUTE = 4
Context level after XECUTE = 3
Context level after routine B = 2
Context level after routine A = 1