Skip to main content
Previous sectionNext section

$GET

Returns the data value of a specified variable.

Synopsis

$GET(variable,default)
$G(variable,default)

Parameters

Argument Description
variable A local variable, global variable, or process-private 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.

  • $GET(variable) returns the value of the specified variable, or the null string if the variable is undefined. The variable parameter value can be the name of any variable, including a subscripted array element (either local or global).

  • $GET(variable,default) provides a default value to return if the variable is undefined. If the variable is defined, $GET returns its value.

Parameters

variable

The variable whose data value is to be returned.

  • variable can be a local variable, a global variable, or a process-private global (PPG) variable. It can be subscripted or unsubscripted. It cannot be an ObjectScript special variable or a structured system variable (SSVN).

    The variable does not need to be a defined variable. $GET returns the null string for an undefined variable; it does not define the variable. A 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.

  • variable can be a multidimensional object property; it cannot be a non-multidimensional object property. Attempting to use $GET on a non-multidimensional object property results in an <OBJECT DISPATCH> error.

    For example, the %SQL.StatementMetadata class has a multidimensional property columnIndex, and a non-multidimensional property columnCount. In the following example, the first $GET returns a value; the second $GET results in an <OBJECT DISPATCH> error:

      SET x=##class(%SQL.StatementMetadata).%New()
      WRITE $GET(x.columnIndex,"columnIndex property is undefined"),!
      WRITE $GET(x.columnCount,"columnCount property is undefined")
    Copy code to clipboard

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 InterSystems IRIS 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.

You can specify an ObjectScript special variable as default. However, specifying $ZORDER may result in an <UNDEFINED> error, even when variable is defined.

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

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

as:

   IF $GET(^client(i))="" {
      WRITE !!,"Name: No Data" 
      GOTO Level1+3
   }
Copy code to clipboard

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

could not be re-coded as:

   IF $GET(^client(i))="" { QUIT }
   ELSEIF $GET(^client(i))="" {
      WRITE !!,"Name: No Data" 
      GOTO Level1+3
   }
Copy code to clipboard

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 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