$LISTDATA (SQL)

A list function that indicates whether the specified element exists and has a data value.

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')