$LISTDATA (SQL)
Synopsis
$LISTDATA(list[,position])
Arguments
Argument | Description |
---|---|
list | An expression that evaluates to a valid list. A list is an encoded character string containing one or more elements. You can create a list using the SQL or ObjectScript $LISTBUILD or $LISTFROMSTRING functions. You can extract a list from an existing list using the SQL or ObjectScript $LIST function. |
position | Optional — An integer expression specifying an element in list. |
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 Embedded SQL examples show the results of the various values of the position argument.
All of the following $LISTDATA statements return a value of 1:
KILL Y SET a=$LISTBUILD("Red",,Y,"","Green") &sql(SELECT $LISTDATA(:a), $LISTDATA(:a,1), $LISTDATA(:a,4), $LISTDATA(:a,5), $LISTDATA(:a,-1) INTO :b,:c, :d, :e, :f) IF SQLCODE'=0 { WRITE !,"Error code ",SQLCODE } ELSE { WRITE !,"1st element status ",b ; 1st element default WRITE !,"1st element status ",c ; 1st element specified WRITE !,"4th element status ",d ; 4th element null string WRITE !,"5th element status ",e ; 5th element in 5-element list WRITE !,"last element status ",f ; last element in 5-element list }
The following $LISTDATA statements return a value of 0 for the same five-element list:
KILL Y SET a=$LISTBUILD("Red",,Y,"","Green") &sql(SELECT $LISTDATA(:a,2), $LISTDATA(:a,3), $LISTDATA(:a,0), $LISTDATA(:a,6) INTO :b,:c, :d, :e) IF SQLCODE'=0 { WRITE !,"Error code ",SQLCODE } ELSE { WRITE !,"2nd element status ",b ; 2nd element is undefined WRITE !,"3rd element status ",c ; 3rd element is killed variable WRITE !,"0th element status ",d ; zero position nonexistent WRITE !,"6th element status ",e ; 6th element in 5-element list }
Notes
Invalid Argument Values
If the expression in the list argument does not evaluate to a valid list, an SQLCODE -400 fatal error occurs:
&sql(SELECT $LISTDATA('fred') INTO :b) IF SQLCODE'=0 { WRITE !,"Error code ",SQLCODE } ELSE { WRITE !,"The the element is ",b }
If the value of the position argument is less than -1, an SQLCODE -400 fatal error occurs:
SET a=$LISTBUILD("Red","Blue","Green") &sql(SELECT $LISTDATA(:a,-3) INTO :c) IF SQLCODE'=0 { WRITE !,"Error code ",SQLCODE } ELSE { WRITE !,"A neg-num position status ",c }
This does not occur when position is a nonnumeric value:
SET a=$LISTBUILD("Red","Blue","Green") &sql(SELECT $LISTDATA(:a,'g') INTO :c) IF SQLCODE'=0 { WRITE !,"Error code ",SQLCODE } ELSE { WRITE !,"Error code ",SQLCODE WRITE !,"A nonnumeric position status ",c }
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