When you need to set up a stratified scheme where one level of subroutines use one error trap setting and another more nested subroutine uses a different one; the more nested subroutine must NEW $ETRAP. When $ETRAP is NEWed, its old value is saved, and its current value is made equal to the empty string. A subsequent SET $ETRAP=<new-value> then establishes the error trapping code for the current execution level.
The QUIT command that reverts to the calling routine causes the NEWed values to be unstacked, including the one for $ETRAP.
If an error occurs while executing at the current execution level (or at an execution level farther from the initial base stack frame), the code from the current $ETRAP gets executed. Unless there is a GOTO or ZGOTO, when the execution of that code is complete, control reverts to the implicit QUIT command that returns to the calling routine. At this time, any prior value of $ETRAP is reinstated.
While at the more nested execution level(s), if an error occurs, the code from the current $ETRAP is executed. After the QUIT to a less nested level, the code from the current $ETRAP gets executed. The current $ETRAP may be different from the $ETRAP at the time of the error due to unstacking. This behavior continues until one of the following possible situations occur:
$ECODE is empty. When the value of $ECODE is equal to the empty string, error processing is no longer active, and normal processing resumes.
An execution level is reached where the value of $ETRAP is empty ($ZTRAP might be non-empty at that level). When the values of both $ZTRAP and $ETRAP are equal to the empty string, no error trapping is active and the process repeats.
The stack is reduced to an empty state. When there is no previous level left to QUIT into, GT.M returns to the operating system level shell. A frame that is in direct mode stops the process by putting the user back into the Direct Mode shell.
When dealing with stratified error trapping, it is important to be aware of two additional intrinsic variables: $STACK and $ESTACK. The values of both of these variables indicate the current execution level. The value of $STACK is an “absolute” value that counts from the start of the GT.M process, whereas the value of $ESTACK restarts at zero (0) each time $ESTACK is NEWed.
It is often beneficial to NEW both $ETRAP and $ESTACK a the same time.