Caché MultiValue Basic Reference
$GET
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Returns the data value of a specified variable.
Synopsis
$GET(variable[,default])
Parameters
variable A local, global, or process-private global variable, subscripted or unsubscripted. The variable may be undefined. variable may be specified as an object property with the syntax obj->property.
default Optional — An expression that resolves to a value to be returned if the variable is undefined. If default is a variable it must be defined, even when not used.
Description
$GET returns the data value of a specified variable. The handling of undefined variables depends on whether you specify a default parameter.
Handling Undefined Variables
$GET defines handling behavior if a specified variable is undefined. The basic form of $GET returns a null string ("") if the specified variable is undefined.
$DATA tests if a specified variable is defined. It returns 0 if the variable is undefined.
The Undefined property of the Config.Miscellaneous class defines handling behavior for all undefined variables system-wide. The Undefined() method of the %SYSTEM.Process class defines handling behavior for all undefined variables for the current process. Setting this property or method has no effect on $GET or $DATA handling of specified variables.
Parameters
variable
The variable whose data value is to be returned. It can be a local variable, a global variable, or a process-private global variable. It can be either subscripted or unsubscripted. It can be a multidimensional object property. The variable does not need to be a defined variable. The variable can be defined and set to the null string (""). If a global variable, it can contain an extended global reference. If a subscripted global variable, it can be specified using a naked global reference. Even when referencing an undefined subscripted global variable, variable resets the naked indicator, affecting future naked global references, as described below.
$GET should not be used on system variables (@ variables). It always returns the null string for all @ variables, whether or not the @ variable currently has a value.
default
The data value to be returned if variable is undefined. It can be any expression, including a local variable, a global variable, or a process-private global variable, either subscripted or unsubscripted. default can be a system variable (@ variable), with or without a non-null value.
If default is a local variable, a global variable, or a process-private global variable, it must be defined variable. If default is an undefined variable, $GET issues an <UNDEFINED> error, even when variable is defined.
If default is a global variable, it can contain an extended global reference. If a subscripted global variable, it can be specified using a naked global reference. If present, default resets the naked indicator, affecting future naked global references.
Examples
In the following example, the variable test is defined and the variable xtest is undefined:
test="banana"
tdef=$GET(test)
tundef=$GET(xtest)
PRINT tdef    ! $GET returned value of test
PRINT tundef  ! $GET returned null string for xtest
PRINT $GET(xtest,"none") 
              ! $GET returns default of "none" for undefined xtest 
In the following example, a multidimensional property is used as the variable value. This example returns the names of defined namespaces:
obj = "%ResultSet"->%New("%SYS.Namespace:List")
obj->Execute()
crt $GET(obj->Data,"none") ! returns "none"
obj->Next()
crt $GET(obj->Data,"none") ! returns "none"
crt $GET(obj->Data("Nsp")) ! returns "%SYS"
obj->Next()
crt $GET(obj->Data("Nsp")) ! returns next namespace
obj->Next()
crt $GET(obj->Data("Nsp")) ! returns next namespace
A similar program returns the same information using the $DATA function.
Notes
$GET Compared to $DATA
$GET provides an alternative to $DATA tests for both undefined variables ($DATA=0) and array nodes that are downward pointers without data ($DATA=10). If the variable is either undefined or a pointer array node without data, $GET returns a null string ("") without an undefined error.
Note that $DATA tests are more specific than $GET tests because they allow you to distinguish between undefined elements and elements that are downward pointers only.
See Also