$LISTDATA
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