Running %STACK
You execute %STACK by entering the following command:
As shown in this example, the %STACK utility displays the current process stack without variables.
Level Type Line Source
1 SIGN ON
2 DO ~DO ^StackTest
3 NEW ALL/EXCL NEW (E)
4 DO TEST+1^StackTest SET A=1 ~DO TEST1 QUIT ;level=2
5 NEW NEW A
6 DO TEST1+1^StackTest ~DO TEST2 ;level = 3
7 ERROR TRAP SET $ZTRAP="TrapLabel^StackTest"
8 XECUTE TEST2+2^StackTest ~XECUTE "SET A=$$TEST3()"
9 $$EXTFUNC ^StackTest ~SET A=$$TEST3()
10 PARAMETER AA
11 DIRECT BREAK TEST3+1^StackTest ~BREAK
12 DO ^StackTest ~DO ^%STACK
Under the current execution stack display, %STACK prompts you for a Stack Display Action. You can get help by entering a question mark (?) at this prompt. You can exit %STACK by pressing the Return key at this prompt.
Displaying the Process Execution Stack
Depending on what you enter at the Stack Display Action prompt, you can display the current process execution stack in four forms:
-
Without variables, by entering *F
-
With a specific local variable, by entering *V
-
With all local variables, by entering *P
-
With all local variables, preceded by a list of process state variables, by entering *A
%STACK then displays the Display on Device prompt, enabling you to specify where you want this information to go. Press the Return key to display this information to the current device.
Displaying the Stack without Variables
The process execution stack without variables appears when you first enter the %STACK utility or when you type *F at the Stack Display Action prompt.
Displaying the Stack with a Specific Variable
Enter *V at the Stack Display Action prompt. This will prompt you for the name(s) of the local variable(s) you want to track through the stack. Specify a single variable or a comma-separated list of variables. It returns the names and values of all local variables. In the following example, the variable e is being tracked and the display is sent to the Terminal by pressing Return
Stack Display Action: *V
Now loading variable information ... 2 done.
Variable(s): e
Display on
Device: <RETURN>
Displaying the Stack with All Defined Variables
Enter *P at the Stack Display Action prompt to see the process execution stack together with the current values of all defined local variables.
Displaying the Stack with All Variables, including State Variables
Enter *A at the Stack Display Action prompt to display all possible reports. Reports are issued in the following order:
Understanding the Stack Display
Each item on the stack is called a frame. The following table describes the information provided for each frame.
%STACK Utility Information
Heading |
Description |
Level |
Identifies the level within the stack. The oldest item on the stack is number 1. Frames without an associated level number share the level that first appears above them. |
Type |
Identifies the type of frame on the stack, which can be: DIRECT BREAK: A BREAK command was encountered that caused a return to direct mode. DIRECT CALLIN: An InterSystems IRIS process was initiated from an application outside of InterSystems IRIS, using the InterSystems IRIS call-in interface. DIRECT ERROR: An error was encountered that caused a return to direct mode. DO: A DO command was executed. ERROR TRAP: If a routine sets $ZTRAP, this frame identifies the location where an error will cause execution to continue. FOR: A FOR command was executed. NEW: A NEW command was executed. If the NEW command had arguments, they are shown. SIGN ON: Execution of the InterSystems IRIS process was initiated. XECUTE: An XECUTE command was executed. An $XECUTE function was executed. $$EXTFUNC: A user-defined function was executed. |
Line |
Identifies the ObjectScript source line associated with the frame, if available, in the format label+offset^routine. |
Source |
Shows the source code for the line, if it is available. If the source is too long to display in the area provided, horizontal scrolling is available. If the device is line- oriented, the source wraps around and continued lines are preceded with .... |
The following table shows whether level, line, and source values are available for each frame type. A "No" under Level indicates that the level number is not incremented and no level number appears in the display.
Frame Types and Values Available
Frame Type |
Level |
Line |
Source |
DIRECT BREAK |
Yes |
Yes |
Yes |
DIRECT CALL IN |
Yes |
No |
No |
DIRECT ERROR |
Yes |
Yes |
Yes |
DO |
Yes |
Yes* |
Yes |
ERROR TRAP |
No |
No |
No, but the new $ZTRAP value is shown. |
FOR |
No |
Yes |
Yes |
NEW |
No |
No |
Shows the form of the NEW (inclusive or exclusive) and the variables affected. |
PARAMETER |
No |
No |
Shows the formal parameter list. If a parameter is passed by reference, shows what other variables point to the same memory location. |
SIGN ON |
Yes |
No |
No |
XECUTE |
Yes |
Yes* |
Yes |
$$EXTFUNC |
Yes |
Yes* |
Yes |
* The LINE value is blank if these are invoked from the Terminal prompt. |
Moving through %STACK Display
If a %STACK display fills more than one screen, you see the prompt -- more -- in the bottom left corner of the screen. At the last page, you see the prompt -- fini --. Type ? to see key presses you use to maneuver through the %STACK display.
- - - Filter Help - - -
<space> Display next page.
<return> Display one more line.
T Return to the beginning of the output.
B Back up one page (or many if arg>1).
R Redraw the current page.
/text Search for \qtext\q after the current page.
A View all the remaining text.
Q Quit.
? Display this screen
# specify an argument for B, L, or W actions.
L set the page length to the current argument.
W set the page width to the current argument.
You enter any of the commands listed above whenever you see the -- more -- or -- fini -- prompts.
For the B, L and W commands, you enter a numeric argument before the command letter. For instance, enter 2B to move back two pages, or enter 20L to set the page length to 20 lines.
Be sure to set your page length to the number of lines which are actually displayed; otherwise, when you do a page up or down, some lines may not be visible. The default page length is 23.
Displaying Variables at Specific Stack Level
To see the variables that exist at a given stack frame level, enter ?# at the Stack Display Action prompt, where # is the stack frame level. The following example shows the display if you request the variables at level 1.
Stack Display Action: ?1
The following Variables are defined for Stack Level: 1
E
Stack Display Action:
You can also display this information using the %SYS.ProcessQueryOpens in a new tab VariableList class query.
Displaying Stack Levels with Variables
You can display the variables defined at all stack levels by entering ?? at the Stack Display Action prompt. The following example shows a sample display if you select this action.
Stack Display Action: ??
Now loading variable information ... 19
Base Stack Level: 5
A
Base Stack Level: 3
A B C D
Base Stack Level: 1
E
Stack Display Action:
Displaying Process State Variables
To display the process state variables, such as $IO, enter *S at the “Stack Display Action” prompt. You will see these defined variables (Process State Intrinsics) as listed in the following table:
Process State Intrinsics |
Documentation |
$D = |
$DEVICE special variable |
$EC = ,M9, |
$ECODE special variable |
$ES = 4 |
$ESTACK special variable |
$ET = |
|
$H = 64700,50668 |
$HOROLOG special variable |
$I = |TRM|:|5008 |
$IO special variable |
$J = 5008 |
$JOB special variable |
$K = $c(13) |
$KEY special variable |
$P = |TRM|:|5008 |
$PRINCIPAL special variable |
$Roles = %All |
$ROLES special variable |
$S = 268315992 |
$STORAGE special variable |
$T = 0 |
$TEST special variable |
$TL = 0 |
$TLEVEL special variable |
$USERNAME = glenn |
$USERNAME special variable |
$X = 0 |
$X special variable |
$Y = 17 |
$Y special variable |
$ZA = 0 |
$ZA special variable |
$ZB = $c(13) |
$ZB special variable |
$ZC = 0 |
$ZCHILD special variable |
$ZE = <DIVIDE> |
$ZERROR special variable |
$ZJ = 5 |
$ZJOB special variable |
$ZM = RY\Latin1\K\UTF8\ |
$ZMODE special variable |
$ZP = 0 |
$ZPARENT special variable |
$ZR = ^||a |
$ZREFERENCE special variable |
$ZS = 262144 |
$ZSTORAGE special variable |
$ZT = |
$ZTRAP special variable |
$ZTS = 64700,68668.58 |
$ZTIMESTAMP special variable |
$ZU(5) = USER |
$NAMESPACE |
$ZU(12) = c:\intersystems\iris\mgr\ |
NormalizeDirectory()Opens in a new tab |
$ZU(18) = 0 |
Undefined()Opens in a new tab |
$ZU(20) = USER |
UserRoutinePath()Opens in a new tab |
$ZU(23,1) = 5 |
|
$ZU(34) = 0 |
|
$ZU(39) = USER |
SysRoutinePath()Opens in a new tab |
$ZU(55) = 0 |
LanguageMode()Opens in a new tab |
$ZU(56,0) = $Id: //iris/2018.1.1/kernel/common/src/emath.c#1 $ 0 |
|
$ZU(56,1) = 1349 |
|
$ZU(61) = 16 |
|
$ZU(61,30,n) = 262160 |
|
$ZU(67,10,$J) = 1 |
JobTypeOpens in a new tab |
$ZU(67,11,$J) = glenn |
UserNameOpens in a new tab |
$ZU(67,12,$J) = TRM: |
ClientNodeNameOpens in a new tab |
$ZU(67,13,$J) = |
ClientExecutableNameOpens in a new tab |
$ZU(67,14,$J) = |
CSPSessionIDOpens in a new tab |
$ZU(67,15,$J) = 127.0.0.1 |
ClientIPAddressOpens in a new tab |
$ZU(67,4,$J) = 0^0^0 |
StateOpens in a new tab |
$ZU(67,5,$J) = %STACK |
RoutineOpens in a new tab |
$ZU(67,6,$J) = USER |
NameSpaceOpens in a new tab |
$ZU(67,7,$J) = |TRM|:|5008 |
CurrentDeviceOpens in a new tab |
$ZU(67,8,$J) = 923 |
LinesExecutedOpens in a new tab |
$ZU(67,9,$J) = 46 |
GlobalReferencesOpens in a new tab |
$ZU(68,1) = 0 |
NullSubscripts()Opens in a new tab |
$ZU(68,21) = 0 |
SynchCommit()Opens in a new tab |
$ZU(68,25) = 0 |
|
$ZU(68,27) = 1 |
|
$ZU(68,32) = 0 |
ZDateNull()Opens in a new tab |
$ZU(68,34) = 1 |
AsynchError()Opens in a new tab |
$ZU(68,36) = 0 |
|
$ZU(68,40) = 0 |
SetZEOF()Opens in a new tab |
$ZU(68,41) = 1 |
|
$ZU(68,43) = 0 |
OldZU5()Opens in a new tab |
$ZU(68,5) = 1 |
BreakMode()Opens in a new tab |
$ZU(68,6) = 0 |
|
$ZU(68,7) = 0 |
RefInKind()Opens in a new tab |
$ZU(131,0) = MYCOMPUTER |
|
$ZU(131,1) = MYCOMPUTER:IRIS |
|
$ZV = IRIS for Windows (x86-64) 2018.1.0 (Build 527U) Tue Feb 20 2018 22:47:10 EST |
$ZVERSION special variable |
Printing the Stack and/or Variables
When you select the following actions, you can choose the output device: