$STack()

Returns strings describing aspects of the execution environment.

The format for the $STACK function is:

$ST[ACK](intexpr[,expr])
[Note] Note

$STACK() returns similar information to ZSHOW "S" when ""=$ECODE, but when $ECODE contains error information, $STACK() returns information as of the time of a prior error, generally the first entry in $ECODE. For $STACK() to return current information, be sure that error handing code does a SET $ECODE="" before restoring the normal flow of control.

Examples of $STACK()

Example:

/usr/lib/fis-gtm/V5.4-002B_x86/gtm -run ^dstackex
dstackex;
  zprint ^dstackex
  write !,$STACK
  xecute "WRITE !,$STACK"
  do Label
  write !,$$ELabel
  write !,$STACK
  quit
 
Label
  write !,$STACK
  do DLabel
  quit
 
ELabel()
  quit $STACK
 
DLabel
  write !,$STACK
  quit
0
1
1
2
1

Example for error processing:

GTM>zprint ^debugerr
debugerr;
 set dsm1=$stack(-1)
 write !,"$stack(-1):",dsm1
 for l=dsm1:-1:0 do
 . write !,l
 . for i="ecode","place","mcode" write ?5,i,?15,$stack(l,i),!
GTM>

The above example can be used to display a trace of the code path that led to an error.

Example:

GTM>zprint ^dstacktst
dstacktst(x)       ; check $stack() returns with and without clearing $ecode
 set $etrap="do ^debugerr"
label
 if x>0 set $ecode=",U1," ; if condition
 else  set $ecode=",U2," ;  else condition
 quit
GTM>do ^dstacktst(0)
$stack(-1):2
2    ecode
     place     debugerr+3^debugerr
     mcode      for l=dsm1:-1:0 do
1    ecode     ,U2,
     place     label+2^dstacktst
     mcode      else  set $ecode=",U2," ;  else condition
0    ecode
     place     +1^GTM$DMOD
     mcode
%GTM-E-SETECODE, Non-empty value assigned to $ECODE (user-defined error trap)
GTM>do ^dstacktst(1)
$stack(-1):1
1    ecode     ,U2,
     place     label+2^dstacktst
     mcode      else  set $ecode=",U2," ;  else condition
0    ecode
     place     +1^GTM$DMOD
     mcode
%GTM-E-SETECODE, Non-empty value assigned to $ECODE (user-defined error trap)
GTM>set $ecode=""
GTM>do ^dstacktst(1)
$stack(-1):2
2    ecode
     place     debugerr+3^debugerr
     mcode      for l=dsm1:-1:0 do
1    ecode     ,U1,
     place     label+1^dstacktst
     mcode      if x>0 set $ecode=",U1," ; if condition
0    ecode
     place     +1^GTM$DMOD
     mcode
%GTM-E-SETECODE, Non-empty value assigned to $ECODE (user-defined error trap)
GTM>

This example shows how SETing $ECODE=.. makes $STACK() reports current information. Notice how ^do dstacktst(0) and ^dostacktst(1) without clearing $ECODE in between displays information frozen at the time of the first error (else condition).