Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see the InterSystems IRIS Migration Guide and Migrating to InterSystems IRIS, both available on the WRC Distributions page (login required).

$KILL

Deletes variables.

Synopsis

$KILL variable[, ...]

Arguments

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.

Description

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.

Examples

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
Copy code to clipboard

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)
Copy code to clipboard

Notes

$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))
Copy code to clipboard

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.

See Also

Feedback