Caché MultiValue Basic Reference
$LISTNEXT
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Retrieves elements sequentially from a list.
Synopsis
$LISTNEXT(list,ptr,value)
Parameters
list An expression that resolves to a Caché list. A Caché list is created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST.
ptr A pointer to the next element in the list. You must specify ptr as a local variable initialized to 0 to point to the beginning of list. ptr cannot be a global variable or a subscripted variable.
value A local variable used to hold the data value of a list element. value does not have to be initialized before invoking $LISTNEXT. value cannot be a global variable or a subscripted variable.
Description
$LISTNEXT sequentially returns elements in a list. You initialize ptr to 0 before the first invocation of $LISTNEXT. This causes $LISTNEXT to begin returning elements from the beginning of the list. Each successive invocation of $LISTNEXT advances ptr and returns the next list element value to value. The $LISTNEXT function returns 1, indicating that a list element has been successfully retrieved.
When $LISTNEXT reaches the end of the list, it returns 0, resets ptr to 0, and leaves value unchanged from the previous invocation. Because ptr has been reset to 0, the next invocation of $LISTNEXT would start at the beginning of the list.
Caché MVBasic increments ptr using an internal address algorithm. Therefore, the only value you should use to set ptr is 0.
You can use $LISTVALID to determine if list is a valid list. An invalid list causes $LISTNEXT to generate a <LIST> error.
Not all lists validated by $LISTVALID can be used successfully with $LISTNEXT. When $LISTNEXT encounters a list element with a null value, it returns 1 indicating that a list element has been successfully retrieved, advances ptr to the next element, and resets value to be an undefined variable. This can happen with any of the following valid lists: value=$LB(), value=$LB(NULL), value=$LB(,), or when encountering an omitted list element, such as the second invocation of $LISTNEXT on value=$LB("a",,"b").
$LISTNEXT("",ptr,value) returns 0, and does not advance the pointer or set value. $LISTNEXT($LB(""),ptr,value) returns 1, advances the pointer, and set value to the null string ("").
$LISTNEXT and Nested Lists
The following example returns three elements, because $LISTNEXT does not recognize the individual elements in nested lists:
   list=$LISTBUILD("Apple","Pear",$LISTBUILD("Walnut","Pecan"))
   ptr=0
   count=0
   LOOP UNTIL 0=$LISTNEXT(list,ptr,value) 
    count=count+1
    CRT value
   REPEAT
   CRT "End of list:",count,"elements found"
Examples
The following example sequentially returns all the elements in the list:
   list=$LISTBUILD("Red","Blue","Green")
   ptr=0
   count=0
  LOOP UNTIL 0=$LISTNEXT(list,ptr,value) 
    count=count+1
    CRT value
  REPEAT
   CRT "End of list:",count,"elements found"
See Also