$KILL variable[, ...]
|variable||The variable(s) to be deleted by the $KILL command. variable can be a single variable name or a comma-separated list of variable names.|
The $KILL statement deletes the specified variable or comma-separated list of variables. The variables can be local variables, process-private variables, or globals. They do not have to be actual defined variables, but they must be valid variable names. You cannot kill a special variable, even if its value is user-specified. Attempting to do so generates a <SYNTAX> error.
The ASSIGNED function returns 0 if a variable is unassigned or has been deleted.
Using $KILL to delete variables frees up local variable storage space. To determine or set the maximum local variable storage space (in kilobytes), use the ObjectScript $ZSTORAGE special variable. To determine the currently available local variable storage space (in bytes), use the $STORAGE special variable.
In the following example, $KILL deletes local variables a, b, and d. The PRINT returns 3 and 5.
a=1 b=2 c=3 d=4 e=5 $KILL a,b,d PRINT a,b,c,d,e
In the following example, $KILL deletes the process-private global ^||ppglob and all of its subscripts. No other variables are affected.
^||ppglob(1)="fruit" ^||ppglob(1,1)="apples" ^||ppglob(1,2)="oranges" $KILL ^||ppglob PRINT ^||ppglob(1),^||ppglob(1,1)
$KILL and Objects
Object variables (OREFs) automatically maintain a reference count — the number of items currently referring to an object. Whenever you set a variable or object property to refer to an object, Caché increments the object’s reference count. When you $KILL a variable, Caché decrements the corresponding object reference count. When this reference count goes to 0, the object is automatically destroyed; that is, Caché removes it from memory. The object reference count is also decremented when a variable is set to a new value, or when the variable goes out of scope.
In the case of a persistent object, call the %Save() method before removing the object from memory if you wish to preserve changes to the object. The %Delete() method deletes the stored version of a Caché object; it does not remove the in-memory version of that object.
Using $KILL with Arrays
You can use $KILL to delete an entire array or a selected node within an array. The specified array can be a local variable, a process-private global, or a global variable. For further details on global variables with subscripted nodes, see Global Structure in Using Caché Globals.
To delete a global array and all of its subordinate nodes, simply supply the global name to $KILL.
To delete an array node, supply the appropriate subscript. For example, the following $KILL command deletes the node at subscript 1,2. This example uses the ASSIGNED function to return a boolean value indicating whether the variable has been deleted:
^fruitbasket(1)="fruit" ^fruitbasket(1,1)="apples" ^fruitbasket(1,2)="oranges" ^fruitbasket(1,2,1)="navel" ^fruitbasket(1,2,2)="mandarin" PRINT ^fruitbasket(1)," contains ",^fruitbasket(1,1), " and ",^fruitbasket(1,2) PRINT ^fruitbasket(1,2)," contains ",^fruitbasket(1,2,1), " and ",^fruitbasket(1,2,2) $KILL ^fruitbasket(1,2) PRINT "1st level node: ",ASSIGNED(^fruitbasket(1)) PRINT "2nd level node: ",ASSIGNED(^fruitbasket(1,1)) PRINT "Deleted 2nd level node: ",ASSIGNED(^fruitbasket(1,2)) PRINT "3rd level node under deleted 2nd: ",ASSIGNED(^fruitbasket(1,2,1))
When you delete an array node, you automatically delete all nodes subordinate to that node and any immediately preceding node that contains only a pointer to the deleted node. If a deleted node is the only node in its array, the array itself is deleted along with the node.