Contains the number of context frames saved on the call stack.
contains the number for 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.
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, 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
This special variable cannot be modified using the SET
command. Attempting to do so results in a <SYNTAX> error.
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 in Application Mode and Programmer Mode
A routine that is invoked in application mode starts at a different context level than a routine invoked from the programmer mode prompt with a DO
command. The DO
command typed at the programmer mode prompt causes a new context to be created. The following example shows the routine START invoked in application mode and in programmer mode.
Consider the following routine:
; Display the context level and exit
WRITE !,"Context level in routine START is ",$STACK
When you run START in application mode, you see the following display:
Context level in routine START is 0
When you run START in programmer mode (by issuing DO ^START at the terminal prompt), you see the following display:
Context level in routine START is 1
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:
WRITE !,"Context level in routine STA = ",$STACK
WRITE !,"Context level after routine A = ",$STACK
WRITE !,"Context level in routine A = ",$STACK
WRITE !, "Context level after routine B = ",$STACK
WRITE !,"Context level in routine B = ",$STACK
XECUTE "WRITE !,""Context level in XECUTE = "",$STACK"
WRITE !,"Context level after XECUTE = ",$STACK
A sample session using this code might run as follows:
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