Caché SQL Reference
$LISTDATA
|
|
A list function that indicates whether the specified element exists and has a data value.
Synopsis
$LISTDATA(list[,position])
$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.
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.
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.
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
}
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 }
-
-
ObjectScript functions:
$LIST,
$LISTBUILD,
$LISTDATA,
$LISTFIND,
$LISTFROMSTRING,
$LISTGET,
$LISTLENGTH,
$LISTNEXT,
$LISTSAME,
$LISTTOSTRING,
$LISTVALID