$ESTACK contains the number of context frames saved on the call stack for your job from a user-defined point. You specify this point by creating a new copy of $ESTACK using the NEW command.
The $ESTACK special variable is similar to the $STACK special variable. Both contain the number of context frames currently saved on the call stack for your job or process. Caché increments and restores both when changing context. The major difference is that you can reset the $ESTACK count to zero at any point by using the NEW command. You cannot reset the $STACK count.
When a Caché image is started, before any contexts have been saved on the call stack, the values of both $ESTACK and $STACK are zero. Each time a routine calls another routine with DO, the system saves the context of the currently executing routine on the call stack, increments $ESTACK and $STACK, and starts execution of the called routine in the newly created context. The called routine can, in turn, call another routine, and so on. Each time another routine is called, Caché increments $ESTACK and $STACK and places more saved contexts on the call stack.
Issuing a DO command, an XECUTE command, or a call to a user-defined function establishes a new execution context. Issuing a GOTO command does not.
As DO commands, XECUTE commands, or user-defined function references create new contexts, Caché increments the values of $STACK and $ESTACK. As QUIT commands cause contexts to exit, Caché restores the previous contexts from the call stack and decrements the values of $STACK and $ESTACK.
The $ESTACK and $STACK special variables cannot be modified using the SET command. Attempting to do so results in a <SYNTAX> error.
Creates a new copy of $ESTACK with a value of zero (0).
In this way, you can establish a particular context as the $ESTACK level 0 context. As you create new contexts with DO, XECUTE, or user-defined functions, Caché increments this $ESTACK value. However, when you exit the context in which the new $ESTACK was created ($ESTACK at level 0), Caché restores the value of the previous copy of $ESTACK.
The following example shows the effect of a NEW command on $ESTACK. In this example, the MainRoutine displays the initial values of $STACK and $ESTACK (which are the same value). It then calls Sub1. This call increments $STACK and $ESTACK. The NEW command creates a $ESTACK with a value of 0. Sub1 calls Sub2, incrementing $STACK and $ESTACK. Returning to MainRoutine restores the initial values of $STACK and $ESTACK:
The following example demonstrates how the value of $ESTACK is incremented as new contexts are created by issuing DO and XECUTE commands, and decremented as these contexts are exited. It also shows that a GOTO command does not create a new context or increment $ESTACK:
MainNEW$ESTACKWRITE!,"Initial Main: $ESTACK=",$ESTACK// 0DOSub1WRITE!,"Return Main: $ESTACK=",$ESTACK// 0QUITSub1WRITE!,"Sub1 via DO: $ESTACK=",$ESTACK// 1XECUTE"WRITE !,""Sub1 XECUTE: $ESTACK="",$ESTACK"// 2WRITE!,"Sub1 post-XECUTE: $ESTACK=",$ESTACK// 1GOTOSub2Sub1ReturnWRITE!,"Sub1 after GOTO: $ESTACK=",$ESTACK// 1QUITSub2WRITE!,"Sub2 via GOTO: $ESTACK=",$ESTACK// 1GOTOSub1Return
A routine invoked from a program starts at a different context level than a routine you invoke with the DO command from the Terminal prompt. When you enter a DO command at the Terminal prompt, the system creates a new context for the routine called.
The routine you call can compensate by establishing a $ESTACK level 0 context and then use $ESTACK for all context-level references.
Consider the following routine:
START; Establish a $ESTACK Level 0 ContextNEW$ESTACK; Display the $STACK context levelWRITE!,"$STACK level in routine START is ",$STACK; Display the $ESTACK context level and exitWRITE!,"$ESTACK level in routine START is ",$ESTACKQUIT
When you run START from a program, you see the following display:
$STACK level in routine START is 0
$ESTACK level in routine START is 0
When you run START by issuing DO ^START at the Terminal prompt, you see the following display:
$STACK level in routine START is 1
$ESTACK level in routine START is 0