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