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