Skip to main content

$GET (ObjectScript)

Returns the data value of a specified variable.

Synopsis

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

Arguments

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

  • $GET(variable) returns the value of the specified variable, or the null string if the variable is undefined. The variable argument 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.

Arguments

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.StatementMetadataOpens in a new tab 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")

default

The data value to be returned if variable is undefined. It can be 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.

Note that InterSystems IRIS always evaluates default before evaluating variable. Consequently, if default is an undefined variable, $GET issues an <UNDEFINED> error, even if variable is defined. (See the %SYSTEM.Process.Undefined()Opens in a new tab method for information on changing this behavior.)

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 

$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).

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()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class. The system-wide default behavior can be established by setting the UndefinedOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class. Setting Undefined has no effect on $GET or $DATA handling of specified variables.

See Also

FeedbackOpens in a new tab