Caché ObjectScript Reference
$GET
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Returns the data value of a specified variable.
Synopsis
$GET(variable,default)
$G(variable,default)
Parameters
variable A local or global variable, subscripted or unsubscripted. The variable may be undefined. variable may be specified as a multidimensional object property with the syntax obj.property.
default Optional — The value to be returned if the variable is undefined. If a variable, it must be defined.
Description
$GET returns the data value of a specified variable. The handling of undefined variables depends on whether you specify a default parameter.
Parameters
variable
The variable whose data value is to be returned.
default
The data value to be returned if variable is undefined. It can any expression, including a local variable or a global variable, either subscripted or unsubscripted. 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. If present, default resets the naked indicator, affecting future naked global references, as described below.
If default is an undefined variable, by default $GET issues an <UNDEFINED> error, even when variable is defined. You can change Caché behavior to not generate an <UNDEFINED> error when referencing an undefined variable by setting the %SYSTEM.Process.Undefined() method. If the Undefined() method is set to not generate an <UNDEFINED> error, $GET returns variable when default is undefined.
Examples
In the following example, the variable test is defined and the variable xtest is undefined. (The ZWRITE command is used because it explicitly returns a null string value.)
   KILL xtest
   SET test="banana"
   SET tdef=$GET(test),tundef=$GET(xtest)
   ZWRITE tdef    ; $GET returned value of test
   ZWRITE tundef  ; $GET returned null string for xtest
   WRITE !,$GET(xtest,"none") 
     ; $GET returns default of "none" for undefined variable 
 
In the following example, a multidimensional property is used as the variable value. This example returns the names of all defined namespaces:
  SET obj = ##class(%ResultSet).%New("%SYS.Namespace:List")
  DO obj.Execute()
  WRITE !,$GET(obj.Data,"none") // returns "none"
  SET x=1
  WHILE x'="" {
     DO obj.Next()
     SET x=$GET(obj.Data("Nsp"))
     IF x'="" {
     WRITE !,"Namespace: ",x }
   }
   WRITE !,"Done!"
 
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. For example, you can recode the following lines:
   IF $DATA(^client(i))=10 {
      WRITE !!,"Name: No Data" 
      GOTO Level1+3
   }
as:
   IF $GET(^client(i))="" {
      WRITE !!,"Name: No Data" 
      GOTO Level1+3
   }
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. For example, the lines:
  IF $DATA(^client(i))=0 { QUIT }
  ELSEIF $DATA(^client(i))=10 {
    WRITE !!,"Name: No Data" 
    GOTO Level1+3 
  }
could not be re-coded as:
   IF $GET(^client(i))="" { QUIT }
   ELSEIF $GET(^client(i))="" {
      WRITE !!,"Name: No Data" 
      GOTO Level1+3
   }
The two lines perform different actions depending on whether the array element is undefined or a downward pointer without data. If $GET were used here, only the first action (QUIT) would ever be performed. You could use $DATA for the first test and $GET for the second, but not the reverse ($GET for the first test and $DATA for the second).
Defaults with $GET and $SELECT
$GET(variable,default) allows you to return a default value when a specified variable is undefined. The same operation can be performed using a $SELECT function.
However, unlike $SELECT, the second argument in $GET is always evaluated.
The fact that $GET always evaluates both of its arguments is significant if variable and default both make subscripted global references and thus both modify the naked indicator. Because the arguments are evaluated in left-to-right sequence, the naked indicator is set to the default global reference, regardless of the whether $GET returns the default value. For further details on using $GET with global variables and the naked indicator, see Using Multidimensional Storage (Globals) in Using Caché Globals.
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.
You can define handling behavior for all undefined variables on a per-process basis using the Undefined() method of the %SYSTEM.Process class. The system-wide default behavior can be established by setting the Undefined property of the Config.Miscellaneous class. Setting Undefined has no effect on $GET or $DATA handling of specified variables.
See Also