The KILL command deletes local or global variables and their descendant nodes.
The format of the KILL command is:
K[ILL][:tvexpr] [glvn | (glvn[,...]) | *lname | *lvn ]
The optional truth-valued expression immediately following the command is a command postconditional that controls whether or not GT.M executes the command.
The optional global or local variable name specifies the variable to delete; KILL deletes not only the variable specified in the argument, but also all variables descended from that variable, that is, those starting with the identical key-prefix.
KILLing a variable that does not currently exist has no effect.
The KILL command without an argument deletes all currently existing local variables; in this case, at least two (2) spaces must follow the KILL to separate it from the next command on the line.
When a KILL argument consists of local variable names enclosed in parentheses, that "exclusive" KILL deletes all local variables except those listed in the argument.
KILL does not affect copies of local variables that have been "stacked" by NEW or parameter passing with the possible exception of the following:
For KILL arguments enclosed in parentheses, the environment variable gtm_stdxkill enables the standard-compliant behavior to kill local variables in the exclusion list if they had an explicit or implicit (pass-by-reference) alias not in the exclusion list. By default, this behavior is disabled. If gtm_stdxkill is set to 1,"TRUE", or "YES", KILL deletes a local variable unless all its names are in the parenthesized list. If gtm_stdxkill is not defined or set to 0 KILL operations exclude the data associated with an item if any one of its names appears in the parenthesized list. While non-standard, the default behavior decouples call-by-reference functions or functions using aliases from needing knowledge of the caller's parameters.
In conformance with the M standard, KILL of a variable joined by pass-by-reference to a formallist variable always KILLs the formalist variable when the actuallist variable is KILL'd even if the formallist variable is specified as protected by an exclusive KILL.
KILL * removes the association between its argument and any associated arrays. The arguments are left undefined, just as with a standard KILL. If the array has no remaining associations after the KILL *, GT.M can reuse the memory it occupied. If there are no array(s) or association(s) the KILL * happily and silently does nothing.
KILL * of an alias container variable is just like a KILL of an alias variable, and deletes the association between the lvn and the array.
KILL * treats an alias formed though pass-by-reference the same as any alias variable by removing the alias association.
KILL * with no arguments removes all aliases and alias containers connections.
You can intermix KILL and KILL * in an argument list. For example, KILL *A,B
Kill * is not permitted inside a parenthesized list of exclusions, e.g.: KILL (*A) is an error.
An exclusive KILL where one associated name is inside the parenthetic list of exclusions and another associated name is not with that list kills the array through the name that is not inside the list. The association, however, is preserved.
For more information and KILL * examples, refer to “Alias Variables Extensions”.
An indirection operator and an expression atom evaluating to a list of one or more KILL arguments form a legal argument for a KILL.
![[Caution]](../common/images/caution.jpg) | Caution |
|---|---|
Use KILL with caution because it can have a major impact on the process environment (local variables) or shared data (global variables). |
Example:
GTM>Kill Set a=0,a(1)=1,a(1,1)="under" KILL a(1) ZWR a=0 GTM>
This uses an argumentless KILL to get a "fresh start" by deleting all existing local variables. After SETting a, a(1), and a(1,1), the KILL deletes a(1) and its descendants. The ZWRITE shows only a remaining.
Example:
GTM>Kill (a,b),^AB(a,b)
The first argument (an exclusive KILL) specifies to KILL all local variables except a and b. The second argument deletes ^AB(a,b) and any descendants of that global variable node.
Example:
kill *
write !,"gtm_stdxkill=",+$ztrnlnm("gtm_stdxkill"),!
set (A,B,C,E)="input"
do X(.A,.B)
zwrite
write !,"____________",!
set (A,B,C,E)="input"
do Y(.A,.B)
zwrite
write !,"____________",!
set (A,B,C,E)="base"
set *C=A,*D=B
kill (C,D)
zwrite
quit
X(C,D) set (C,D)="output"
kill (C,D)
quit
Y(C,D) set (C,D)="output"
kill (A,C,D)
quitProduces the following output:
gtm_stdxkill=0 A="output" B="output" C="input" ____________ A="output" B="output" C="input" ____________ A="base" ;* B="base" ;* *C=A *D=B
