Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see the InterSystems IRIS Migration Guide and Migrating to InterSystems IRIS, both available on the WRC Distributions page (login required).

$LISTDATA ($LD)

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
Copy code to clipboard

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
Copy code to clipboard

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

Feedback