Caché MultiValue Basic Reference
$LISTDATA ($LD)
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Indicates whether the specified element exists and has a data value.
Synopsis
$LISTDATA(list,position)
$LD(list,position)
Parameters
list An expression that resolves to a Caché list. A Caché list is created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST.
position Optional — An expression that resolves to an integer specifying a position in list. Valid values are -1, 0, and positive integers.
Description
$LISTDATA checks for data in the requested element in a list and returns a boolean value. $LISTDATA returns a value of 1 if the element indicated by the position parameter is in the list and has a data value. $LISTDATA returns a value of a 0 if the element is not in the list or does not have a data value.
Parameters
list
A list is an encoded string containing multiple elements. A list must have been created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST.
position
If you omit the position parameter, $LISTDATA evaluates the first element. If the value of the position parameter is -1, it is equivalent to specifying the final element of the list. If the value of the position parameter refers to a nonexistent list member, then invoking the $LISTDATA function returns a 0.
Examples
The following examples show the results of the various values of the position parameter.
All of the following $LISTDATA statements return a value of 0 (Y is an undefined variable):
x=$LISTBUILD("Red",,Y,"","Green")
PRINT $LISTDATA(x,2);     ! second element is undefined
PRINT $LISTDATA(x,3);     ! third element is undefined variable
PRINT $LISTDATA("");      ! null string
PRINT $LISTDATA(x,0);     ! the 0th position
PRINT $LISTDATA(x,6);     ! 6th position in 5-element list
The following $LISTDATA statements return a value of 1 for the same five-element list:
x=$LISTBUILD("Red",,Y,"","Green")
PRINT $LISTDATA(x);    ! first position (by default)
PRINT $LISTDATA(x,1);  ! first position specified
PRINT $LISTDATA(x,4);  ! fourth position value=null string
PRINT $LISTDATA(x,5);  ! fifth position
PRINT $LISTDATA(x,-1); ! last (5th) position
Notes
Invalid Parameter Values
If the expression in the list parameter does not evaluate to a valid list, a <LIST> error occurs.
If the value of the position parameter is less than -1, invoking the $LISTDATA function generates a <RANGE> error.
See Also