Chapter 11 Caché Function Collection $DATA Function

Chapter 11 Caché Function Collection $DATA Function

Check whether the variable contains data.

Outline

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

parameter

• variable The variable whose status is to be checked. Subscripted or unsubscripted local or global variables. The variable may be undefined. You cannot specify simple object attribute references as variables. You can use the syntax obj.property to specify a multi-dimensional property reference as a variable.
• target optional-a variable that $DATAreturns the current value of the variable.

description

You can use it $DATAto test whether the variable contains data before trying to manipulate it . $DATAReturns status information about the specified variable. The variable parameter can be the name of any variable (local variable, process-specific global variable or global variable) and can contain array elements with subscripts. It can be a multidimensional object attribute. It cannot be a non-multidimensional object attribute.

The possible status values ​​returned are as follows:

State value	meaning
0	The variable is undefined. Any reference will cause an error.
1	The variable exists and contains data, but has no descendants. Please note that the empty string ( “”) meets the data conditions.
10	This variable identifies an array element that has descendants (containing a downward pointer to another array element) but does not contain data. Any direct references to such variables will cause errors. For example, if it is defined y（1but not defined y, it $DATA（y）returns 10, and setting x = y will generate an error.
11	This variable identifies an array element that has descendants (containing a downward pointer to another array element) and contains data. Variables of this type can be referenced in expressions.

You can use modulo 2（＃2arithmetic to $DATAreturn Boolean values: $DATA（var）＃2return 0 for undefined status codes (0 and 10), and return 1 for defined status codes (1 and 1). 11)...

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

You can use ％SYSTEM.Processclass Undefined（）methods to set the behavior when encountering undefined variables.

$DATA Test Locks, Routines, Jobs, Globals

• $DATA(^$LOCK(lockname))Test whether the lock exists. Please note that the return value is different: 0=lock does not exist; 10=lock exists. Unable to determine locked offspring. The values ​​1 and 11 will never be returned.
• $DATA(^$ROUTINE(routinename))Test whether the OBJ code version of the routine exists. Please note that the return value is different: 0=routine OBJ code does not exist; 1=routine OBJ code exists. The values ​​10 and 11 will never be returned.
• $DATA(^$JOB(jobnum))Test whether the JOB exists. Please note that the return value is different: 0=job does not exist; 1=job exists. The values ​​10 and 11 will never be returned.
• $DATA(^$GLOBAL(globalname))Test for the existence of global variables. The return codes are the same as the variables: 0, 1, 10, and 11.

parameter

variable

• Variables that are testing for the existence of data: Variables can be local variables, global variables or process-specific global (PPG) variables. It can be subscripted or not.

If it is a global variable, it can contain extended global variable references. If it is a subscripted global variable, you can use the naked global variable reference to specify it. Even if the undefined subscript global variable is referenced, the variable will reset the naked indicator, which will affect the future reference of naked global variables, as described below.

• Variables can be multidimensional object attributes. It cannot be a non-multidimensional object attribute. Attempting to use non-multidimensional object properties $DATAwill result in <Object Dispatch>errors.

For example, %SQL.StatementMetadataclasses have multi-dimensional attributes column nIndexand non-multidimensional attributes column nCount. In the following example, the first $DATAreturns a value; the second $DATAcauses <OBJECT DISPATCH>an error:

/// d ##class(PHA.TEST.Function).data()
ClassMethod data()
{
    
    
	SET x=##class(%SQL.StatementMetadata).%New()
	WRITE "columnIndex defined: ",$DATA(x.columnIndex),!
	WRITE "columnCount defined: ",$DATA(x.columnCount)
}

DHC-APP>d ##class(PHA.TEST.Function).data()
columnIndex defined: 0
columnCount defined:
 WRITE "columnCount defined: ",$DATA(x.columnCount) }
                               ^
<OBJECT DISPATCH>zdata+3^PHA.TEST.Function.1 *Property 'columnCount' in class '%SQL.StatementMetadata' must be MultiDimensional

$DATAThe data status value of the proxy object property cannot be returned. Instead, Caché sends out a message stating that the specified attribute does not exist. This attribute access restriction ％ZEN.proxyObjectis unique to the class

If the variable is a ^$ROUTINEstructured system variable, the possible return status value is 1 or 0.

target

Optional parameters. Specify the names of local variables, process-specific global variables or global variables. There is no need to define this target variable. If the target is specified, $DATAthe current value of the variable data is written to target. If the variable is not defined, the target value remains unchanged.

ZBREAKThe command cannot specify the target parameter as an observation point.

Example

This example ^ clientwrites the selected range of records from an array (a sparse array consisting of three levels). The first level contains the customer’s name, the second level contains the customer’s address, and the third level contains the customer’s account, account number and balance. A customer can have up to four separate accounts. Because ^client is a sparse array, there may be undefined elements on any of these three levels. The content of a typical record might look like this:

/// d ##class(PHA.TEST.Function).data1()
ClassMethod data1()
{
    
    
	set ^client(5) = "John Jones"
	set ^client(5,1) = "23 Bay Rd./Boston/MA 02049"
	set ^client(5,1,1) = "Checking/45673/1248.00"
	set ^client(5,1,2) = "Savings/27564/3270.00"
	set ^client(5,1,3) = "Reserve Credit/32456/125.00"
	set ^client(5,1,4) = "Loan/81263/460.00"
}

The following code provides a separate subroutine to process the output of each of the three array levels. It uses a $DATAfunction at the beginning of each subroutine to test the current array element.

Level1The test in , Level2and Level3is $DATA = 0used to test whether the current array element is undefined. If TRUE, it will cause the code to exit and return to the previous level.

Level1Level2The $DATA = 10test in and is used to test whether the current array element contains pointers to subordinate elements, but there is no data. If TRUE, it will cause the code to write a "no data" message. Then, the code jumps to the next lower-level FOR loop processing. There Level3is no $DATA = 10test in because there is no element belonging to this level.

Level2And Level3the WRITEcommand $PIECEfunction to extract the appropriate information from the current array element.

/// d ##class(PHA.TEST.Function).data2()
ClassMethod data2()
{
    
    
	Read !, "输出多少条记录: ", n
	Read !, "从记录编号开始: ", s
	For i = s : 1 : s + (n) {
    
    
		If $Data(^client(i)) {
    
    
			If $Data(^client(i)) = 10 {
    
    
				Write !, " 名字: 无数据"
			} Else {
    
    
				Write !, " 名字: " , ^client(i)
			}
			If $Data(^client(i, 1)) {
    
    
				If $Data(^client(i,1 )) = 10 {
    
    
					Write !, "地址: 无数据"
				} Else {
    
    
					Write !, "地址: ",$Piece(^client(i, 1), "/", 1)
					Write " , ", $Piece(^client(i, 1), "/", 2)
					Write " , ", $Piece(^client(i, 1) ,"/", 3)
				}
			}
			For j = 1 : 1 : 4 {
    
    
				If $Data(^client(i, 1, j)) {
    
    
					Write !,"账户: ",$Piece(^client(i, 1, j), "/", 1)
					Write " #: ",$Piece(^client(i, 1, j), "/", 2)
					Write " 结余: ",$Piece(^client(i, 1, j), "/", 3)
				}
			}
		}
	}
	Write !,"结束."
	Quit
}

When executed, this code may produce output similar to the following:

DHC-APP>d ##class(PHA.TEST.Function).data2()
 
输出多少条记录: 2
从记录编号开始: 1
 名字: 无数据
地址: 无数据
账户: Cambridge,MA,02142 #:  结余:
结束.
DHC-APP>d ##class(PHA.TEST.Function).data2()
 
输出多少条记录: 5
从记录编号开始: 5
 名字: John Jones
地址: 23 Bay Rd. , Boston , MA 02049
账户: Checking #: 45673 结余: 1248.00
账户: Savings #: 27564 结余: 3270.00
账户: Reserve Credit #: 32456 结余: 125.00
账户: Loan #: 81263 结余: 460.00
结束.

In the following example, multidimensional attributes are used as variable values. This example returns the names of all defined namespaces to the target parameter:

/// d ##class(PHA.TEST.Function).data3()
ClassMethod data3()
{
    
    
	SET obj = ##class(%ResultSet).%New("%SYS.Namespace:List")
	DO obj.Execute()
	WRITE $DATA(obj.Data,targ),!                // returns 0
	SET targ="blank"
	WHILE targ'="" {
    
    
		DO obj.Next()
		WRITE $DATA(obj.Data,targ)               // returns 10
		WRITE " ",$DATA(obj.Data("Nsp"),targ),!  // returns 1
		IF targ'="" {
    
    
			WRITE "Namespace: ",targ,! 
		}
	}
	WRITE !,"Done!"
}

DHC-APP>d ##class(PHA.TEST.Function).data3()
0
10 1
Namespace: %SYS
10 1
Namespace: DHC-APP
10 1
Namespace: DHC-CHSSWEB
10 1
Namespace: DHC-CSM
10 1
Namespace: DHC-DATA
10 1
Namespace: DHC-DWR
10 1
Namespace: DHC-EKG
10 1
Namespace: DHC-HEIS
10 1
Namespace: DHC-HR
10 1
Namespace: DHC-LISDATA
10 1
Namespace: DHC-LISSRC
10 1
Namespace: DHC-MEDSRC
10 1
Namespace: DHC-MRQ
10 1
Namespace: DOCBOOK
10 1
Namespace: FDBMS
10 1
Namespace: PACS
10 1
Namespace: PIS
10 1
Namespace: RIS
10 1
Namespace: SAMPLES
10 1
Namespace: USER
10 1
 
Done!

Similar programs use $GETfunctions to return the same information.

note

naked global variables

When used with global variables, $DATAset bare indicators. Even if the specified global variable is not defined (status value = 0), the bare indicator will be set.

Subsequent references to the same global variable can use bare global references, as shown in the following example:

/// d ##class(PHA.TEST.Function).data4()
ClassMethod data4()
{
    
    
	IF $DATA(^A(1,2,3))#2 {
    
    
		SET x=^(3)  
	}
}

Global variables in the network environment

Using $DATArepeated references to undefined global variables (for example, undefined ^x的$DATA(^x(1)) always requires network operations to test whether global variables are defined on the ECP server.

After using $DATArepeated references to a defined global variable (for example $DATA(^x(1), an undefined node in which ^xany other node is defined ), as long as the relevant part of the global ( ^x) is in the client cache.