Caché MultiValue Basic Reference
READNEXT
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Reads the next field id from a select list.
Synopsis
READNEXT fieldval [FROM slist] 
   [SETTING var] [[THEN statements] [ELSE statements]]
Arguments
fieldval A variable used to receive a field value from the select list. Optionally, this can be a multilevel specification, with the levels separated by commas: field,value or field,value,subvalue.
slist Optional — A select list. This can be a numbered select list specified as an integer from 0 through 10, or a named select list specified as a variable name. If slist is not specified or is the empty string (""), the default select list (0) is accessed.
SETTING var Optional — When a read error occurs, sets the local variable var to the operating system's error return code. Successful completion returns 0; error return codes are platform-specific. The SETTING clause is executed before the THEN, or ELSE clause. Provided for jBASE compatibility.
Description
The READNEXT statement reads successive field identifiers from a select list, one field identifier per invocation. The field identifier is read from the slist select list into the fieldval variable. Optionally, READNEXT can be used to read successive values or successive subvalues within a field, by specifying a multilevel fieldval variable. (READNEXT can also be used to read successive index identifiers; this is described below.)
You can use any of the following SELECT statements to create a select list: SELECT, SELECTN, SELECTV, SSELECT, SSELECTN, or SSELECTV. These various SELECT statements allow you to specify a numbered or named select list, with field identifiers either sorted or not sorted.
You can optionally specify a THEN clause, an ELSE clause, or both a THEN and an ELSE clause. READNEXT executes the THEN clause if the select list pointer has not reached the end of the select list. The THEN clause is executed even when a field identifier is the null string. READNEXT executes the ELSE clause if the select list pointer has reached the end of the select list, or the select list does not exist. The statements argument can be the NULL keyword, a single statement, or a block of statements terminated by the END keyword. A block of statements has specific line break requirements: each statement must be on its own line and cannot follow a THEN, ELSE, or END keyword on that line.
Note:
READNEXT reads a single field identifier from a select list into a variable. READLIST reads all remaining field identifiers from a select list into a dynamic array.
READNEXT reads the next field identifier in a select list. READPREV reads the previous field identifier in a select list. If READNEXT reaches the end of the select list, it clear the select list. For this reason, a subsequent READPREV cannot read backwards from the end of the select list.
Reading an Index
You can use READNEXT to perform successive reads on an index. The index must have been opened using an OPENINDEX statement. and then selected into a named select list with a SELECTINDEX statement.
You can also perform successive reads on an index using the READNEXT KEY statement.
Emulation
Caché MVBasic, by default, uses select list 0 as the default select list for both internal and external use. By default, D3, Reality, R83, POWER95, MVBase, and IN2 emulations use two distinct default select lists, one internal and one external. The default external select list is 0, and the default internal select list is 10. When READNEXT first accesses the external select list (list 0), it moves this list to the internal select list (10). Thus subsequent READNEXT operations can continue to access this select list, regardless of modifications to list 0. This emulation behavior can be set using $OPTIONS PICK.SELECT.
UniData sets SYSTEM(11) to the SELECT count when using Select List 0. Each invocation of READNEXT decrements this SYSTEM(11) count. READNEXT does not decrement the @SELECTED count.
Examples
The following example illustrates the use of the READNEXT statement. SELECT copies all of the field mark identifiers into Select List 4. Each iteration of READNEXT reads the next field mark identifier from Select List 4 into the area variable:
regions="Northeast":@FM:"Southeast":@FM:"Northwest":@FM:"Southwest"
SELECT regions TO 4 ON ERROR PRINT "Select failed"
FOR x=1 TO 5
  READNEXT area FROM 4
  PRINT area
NEXT
The following example illustrates the use of READNEXT with the THEN and ELSE clauses. SELECTV copies all of the field mark identifiers into Select List mylist. READNEXT reads the next field mark identifier from Select List mylist into the area variable:
regions="Northeast":@FM:"Southeast":@FM:"Northwest":@FM:"Southwest"
SELECT regions TO mylist ON ERROR PRINT "Select failed"
x=1
LOOP WHILE x=1
  READNEXT area FROM mylist THEN PRINT area ELSE x=0
REPEAT
See Also