$LISTDATA (SQL)
Synopsis
$LISTDATA(list[,position])
Description
$LISTDATA checks for data in the requested element in a list. $LISTDATA returns a value of 1 if the element indicated by the position argument 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.
This function returns data of type SMALLINT.
Arguments
list
An encoded character string containing one or more elements. You can create a list using the SQL $LISTBUILD function or the ObjectScript $LISTBUILD function. You can convert a delimited string into a list using the SQL $LISTFROMSTRING function or the ObjectScript $LISTFROMSTRING function. You can extract a list from an existing list using the SQL $LIST function or the ObjectScript $LIST function.
position
If you omit the position argument, $LISTDATA evaluates the first element. If the value of the position argument is -1, it is equivalent to specifying the final element of the list. If the value of the position argument refers to a nonexistent list member, $LISTDATA returns 0.
Examples
The following examples show the results of the various values of the position argument.
All of the following $LISTDATA statements return a value of 1:
SELECT
$LISTDATA($LISTBUILD("Red",,Y,"","Green")),
$LISTDATA($LISTBUILD("Red",,Y,"","Green"),1),
$LISTDATA($LISTBUILD("Red",,Y,"","Green"),4),
$LISTDATA($LISTBUILD("Red",,Y,"","Green"),5),
$LISTDATA($LISTBUILD("Red",,Y,"","Green"),-1)
The following $LISTDATA statements return a value of 0 for the same five-element list:
SELECT
$LISTDATA($LISTBUILD("Red",,Y,"","Green"),2),
$LISTDATA($LISTBUILD("Red",,Y,"","Green"),3),
$LISTDATA($LISTBUILD("Red",,Y,"","Green"),0),
$LISTDATA($LISTBUILD("Red",,Y,"","Green"),6)
Notes
Invalid Argument Values
If the expression in the list argument does not evaluate to a valid list, an SQLCODE -400 fatal error occurs:
SELECT $LISTDATA('fred')
If the value of the position argument is less than -1, an SQLCODE -400 fatal error occurs:
SELECT $LISTDATA($LISTBUILD("Red","Blue","Green"),-3)
This does not occur when position is a nonnumeric value:
SELECT $LISTDATA($LISTBUILD("Red","Blue","Green"),'g')
See Also
-
SQL functions: $LIST, $LISTBUILD, $LISTFIND, $LISTFROMSTRING, $LISTGET, $LISTLENGTH, $LISTSAME, $LISTTOSTRING, $PIECE
-
ObjectScript functions: $LIST, $LISTBUILD, $LISTDATA, $LISTFIND, $LISTFROMSTRING, $LISTGET, $LISTLENGTH, $LISTNEXT, $LISTSAME, $LISTTOSTRING, $LISTVALID