Thanks for your feedback!
Need to tell us more? Click here or use the Feedback button.

Is this page helpful?

Contents

Synopsis
Description
Examples
Context Levels from the Terminal Prompt
$ESTACK and Error Processing
See Also

$ESTACK (ObjectScript)

Contains the number of context frames saved on the call stack from a user-defined point.

Synopsis

$ESTACK
$ES

Description

$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. InterSystems IRIS 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.

Context Frames and Call Stacks

When an InterSystems IRIS 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, InterSystems IRIS 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, InterSystems IRIS increments the values of $STACK and $ESTACK. As QUIT commands cause contexts to exit, InterSystems IRIS 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.

Creating a New $ESTACK

You can create a new copy of $ESTACK in any context by using the NEW command. InterSystems IRIS takes the following actions:

Saves the old copy of $ESTACK.
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, InterSystems IRIS increments this $ESTACK value. However, when you exit the context in which the new $ESTACK was created ($ESTACK at level 0), InterSystems IRIS restores the value of the previous copy of $ESTACK.

Examples

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:

Main
   WRITE !,"Initial: $STACK=",$STACK," $ESTACK=",$ESTACK
   DO Sub1
   WRITE !,"Return: $STACK=",$STACK," $ESTACK=",$ESTACK
   QUIT
Sub1
     WRITE !,"Sub1Call: $STACK=",$STACK," $ESTACK=",$ESTACK
     NEW $ESTACK
     WRITE !,"Sub1NEW: $STACK=",$STACK," $ESTACK=",$ESTACK
     DO Sub2
     QUIT
Sub2
     WRITE !,"Sub2Call: $STACK=",$STACK," $ESTACK=",$ESTACK
     QUIT

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:

Main
   NEW $ESTACK
   WRITE !,"Initial Main: $ESTACK=",$ESTACK   // 0
   DO Sub1
   WRITE !,"Return Main: $ESTACK=",$ESTACK   // 0
   QUIT
Sub1
     WRITE !,"Sub1 via DO: $ESTACK=",$ESTACK  // 1
     XECUTE "WRITE !,""Sub1 XECUTE: $ESTACK="",$ESTACK"   // 2
     WRITE !,"Sub1 post-XECUTE: $ESTACK=",$ESTACK   // 1
     GOTO Sub2
Sub1Return
     WRITE !,"Sub1 after GOTO: $ESTACK=",$ESTACK  // 1
     QUIT
Sub2
     WRITE !,"Sub2 via GOTO: $ESTACK=",$ESTACK   // 1
     GOTO Sub1Return

Context Levels from the Terminal Prompt

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 Context
  NEW $ESTACK
    ; Display the $STACK context level
  WRITE !,"$STACK level in routine START is ",$STACK
   ; Display the $ESTACK context level and exit
  WRITE !,"$ESTACK level in routine START is ",$ESTACK
  QUIT

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

$ESTACK and Error Processing

$ESTACK is particularly useful during error processing when error handlers must unwind the call stack to a specific context level. See Using Try-Catch for more information about error processing.