$ZTIMEOUT controls a single process wide timer. The format of the $ZTIMEOUT ISV is:
$ZTIMeout=([timeout][:labelref])
The optional timeout in seconds specifies with microsecond accuracy how long from the current time the timer interrupts the process. If the specified timeout is negative, GT.M cancels the timer. If the timeout is zero, GT.M treats it as it would a DO of the vector.
The optional labelref specifies a code vector defining a fragment of M code to which GT.M transfers control as if with a DO when the timeout expires. If the timeout is missing, the assignment must start with a colon and only changes the vector, and in this case, if the timeout is the empty string, GT.M removes any current vector.
Note that GT.M only recognizes interrupts such as from $ZTIMEOUT at points where it can properly resume operation, such as the beginning of a line, when waiting on a command with a timeout, or when starting a FOR iteration. GT.M defers recognition of a $ZTIMEOUT arriving while executing a TP transaction until after a TROLLBACK or the "master" TCOMMIT. When a timeout occurs, if the last assignment specified no vector, GT.M uses the current $ETRAP or $ZTRAP. When a $ZTIMEOUT expires, it invokes one of three possible vectors:
Its own labelref, which creates a new stack frame, from which it returns to the point at which it was recognized - similar to what happens for $ZINTERUPT when it recognizes a MUPIP INTRPT; see WARNING below
If labelref is not specified and $ETRAP is specified, it envokes the $ETRAP code, which it acts like an error and operates as if in the current frame, implicitly dropping the current frame when the $ETRAP vector processing completes
If labelref is not specified and $ZTRAP is specified, it invokes the $ZTRAP code, acting like an error whose behavior is subject to $gtm_ztrap_form; for additional information, refer to the $ZTRAP documentation
In all cases the invoked code can alter the behavior using the tools at its disposal - for example, GOTO, ZGOTO, $ECODE, etc.
![[Caution]](images/caution.jpg) |
Warning |
|---|---|
|
When none of the vectors are specified, a $ZTIMEOUT expiration results in the termination of the process Using a [Z}GOTO that stays within a $ZTIMEOUT labelref vector frame may cause undefined and undesirable behavior |
GT.M rejects an attempted KILL of $ZTIMeout with the VAREXPECTED error and an attempted NEW of $ZTIMeout with the SVNONEW error.
Example:
GTM>zprint ^ztimeout
ztimeout
; Display $ztimeout
write !,$ztimeout ; display $ZTIMeout - in this case the initial value -1
; set with a vector (do ^TIMEOUT)
set $ztimeout="60:do ^TIMEOUT" ; timeout of 1 minute. After timeout expires, XECUTEs do ^TIMEOUT
write !,$ztimeout ; displays the remaining time:vector until timeout
; set without a vector
set $ztimeout=120 ; set the timeout to 2 minutes without changing the vector
set $ztimeout="1234do ^TIMEOUT" ; missing colon creates a timeout for 1234 seconds
set $ztimeout="10:" ; set the timeout to 10 seconds and vector to current etrap or ztrap
set $ztimeout=-1 ; set cancels the timeout
; Note that set to 0 triggers an immediate timeout
set $ztimeout=0 ; triggers the current vector
set $ztimeout="0:DO FOO" ; this has the same effect as DO FOO
GTM>