$STack()

Returns strings describing aspects of the execution environment.

The format for the $STACK function is:

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

The intexpr identifies the M virtual machine stack level (as described by the standard), on which the function is to provide information.
The optional second argument is evaluated as a keyword that specifies a type of information to be returned as follows:
- “MCODE” the line of code that was executed.
- “PLACE” the address of the above line of code or the symbol at ("@") to indicate code executed from a string value.
  [Note] Note
  For run-time errors, GT.M does not provide a “PLACE” within a line (unlike it does for compilation errors), but it reports a label, offset, and routine.
- “ECODE” either an empty string, or the error code(s) that was added at this execution level.
When $STACK has only one argument, values corresponding to available stack levels specify a return value that indicates how the level was created, as follows:
If intexpr is zero (0), the function returns information on how GT.M was invoked.
If intexpr is minus one (-1), the function returns the highest level for which $STACK can return information. Note that, if $ECODE="", $STACK(-1) returns the same value as the $STACK ISV.
If intexpr is greater than zero (0) and less than or equal to $STACK(-1), indicates how this level of process stack was created (“DO”, “TRIGGER” - for a stack level invoked by a trigger, “XECUTE”, or “$$” - for an extrinsic function).
$STACK(lvl) reports “ZINTR” for a stack level invoked by MUPIP INTRPT.
If intexpr is greater than $STACK (-1), the function returns an empty string.
During error handling, $STACK() return a snapshot of the state of the stack at the time of error. Even if subsequent actions add stack levels, $STACK() continues to report the same snapshot for the levels as of the time of the error. $STACK() reports the latest stack information only after the code clears $ECODE.
$STACK() assists in debugging programs.


[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).


[Note]	Note
For run-time errors, GT.M does not provide a “PLACE” within a line (unlike it does for compilation errors), but it reports a label, offset, and routine.