Skip to main content

$GET

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.

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

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 UndefinedOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class defines handling behavior for all undefined variables system-wide. The Undefined()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab 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

FeedbackOpens in a new tab