Skip to main content

This is documentation for Caché and Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

Please read this important announcement about the future of Caché and Ensemble maintenanceOpens in a new tab. Contact your account team to migrate to InterSystems IRIS.

$DATA ($D)

Checks if a variable contains data.

Synopsis

$DATA(variable,target)
$D(variable,target)

Parameters

variable The variable whose status is to be checked. variable may be specified as a variable or an object property with the syntax obj->property. If variable is not a valid variable or property name, MVBasic issues a syntax error.
target Optional — A variable into which $DATA returns the current value of variable. target may be specified as a variable or an object property with the syntax obj->property. If target is not a valid variable or property name, MVBasic issues a syntax error.

Description

You can use $DATA to test whether a variable contains data before attempting an operation on it. $DATA returns status information about the specified variable. The variable parameter can be the name of any variable (local variable, process-private global, or global), and can include a subscript (an array element).

The possible status values that may be returned are as follows:

Status Value Meaning
0 The variable is undefined and has no descendents.
1 The variable contains data and has no descendants. Note that the null string ("") qualifies as data.
10 The variable is undefined, but has descendants that contain data. Status 10 identifies an array element that has descendants (contains a downward pointer to another array element) but does not itself contain data.
11 The variable contains data and has descendents. Status 11 identifies a defined array element that has descendants (contains a downward pointer to another array element that also contains data). Variables of this type can be referenced in expressions.
Note:

Status values 1 and 11 indicate only the presence of data, not the type of data.

If $DATA(var) returns either 0 or 10, any direct reference to var will result in an <UNDEFINED> error. For more information on <UNDEFINED> errors, refer to the $ZERROR special variable.

You can also use the EXISTS function to determine if a variable is defined and whether a dimensioned array element has descendants (subnodes).

Parameters

variable

The variable can be a local variable, a process-private global, or a global, with or without subscripts. It can be a multidimensional object property. If a global variable, it can include an extended global reference. If a subscripted global variable, it can be a naked global reference.

Note:

$DATA should not be used on system variables (@ variables). It always returns 0 for all @ variables, whether or not the @ variable currently has a value.

target

An optional parameter. Specify the name of a local variable, a process-private global, or a global variable, with or without subscripts. This target variable does not need to be defined.

  • If variable contains data and target is defined, $DATA copies the variable value to target.

  • If variable contains data and target is undefined, $DATA creates the target variable and copies the variable value to target.

  • If variable does not contain data and target is undefined, target remains undefined.

  • If variable does not contain data and target is defined, the existing target value remains unchanged.

variable and target may be the same variable.

Examples

In the following example, a multidimensional property is used as the variable value. This example returns the names of all defined namespaces to the target parameter:

obj = "%ResultSet"->%New("%SYS.Namespace:List")
obj->Execute()
crt $DATA(obj->Data)               ! returns 0
obj->Next()
crt $DATA(obj->Data)               ! returns 10
crt $DATA(obj->Data("Nsp"),targ)   ! returns 1
crt targ                           ! returns namespace name
obj->Next()
crt $DATA(obj->Data("Nsp"),targ)   ! returns 1
crt targ                           ! returns namespace name

A similar program returns the same information using the $GET function.

Notes

Naked Global References

$DATA sets the naked indicator when used with a global variable. The naked indicator is set even if the specified global variable in not defined (Status Value = 0).

Subsequent references to the same global variable can use a naked global reference.

For further details on using $DATA with global variables and naked global references, see Using Multidimensional Storage (Globals) in Using Caché Globals.

Global References in a Networked Environment

Using $DATA to repeatedly reference a global variable that is not defined (for example, $DATA(^x(1)) where ^x is not defined) always requires a network operation to test if the global is defined on the ECP server.

Using $DATA to repeatedly reference undefined nodes within a defined global variable (for example, $DATA(^x(1)) where any other node in ^x is defined) does not require a network operation once the relevant portion of the global (^x) is in the client cache.

For further details, refer to Developing Distributed Applications in the Caché Distributed Data Management Guide.

$DATA and $ORDER

For related information, see $ORDER. Since $ORDER selects the next element in an array that contains data, it avoids the need to perform $DATA tests when looping through array subscripts.

See Also

Next sectionDATE
Previous sectionCOUNTS
FeedbackOpens in a new tab