READNEXT |
![]() ![]() ![]() |
The READNEXT statement returns the next item from an active select list.
Format
READNEXT var {, val.pos {, subval.pos}} {FROM list.no} {ON ERROR statement(s)} {THEN statement(s)} {ELSE statement(s)}
where
At least one of the THEN and ELSE clauses must be present.
The next item in the specified select list is removed from the list and stored in var. Although the list may be of any size, a single item extracted by READNEXT cannot exceed 32k bytes. Attempting to extract an item larger than this limit will be handled as a fatal error as described below.
The ON ERROR clause is executed if a fatal error occurs. The STATUS() function will return an value relating to the error. If no ON ERROR clause is present, fatal errors result in an abort.
The THEN clause is executed if the select list was active and not empty.
The ELSE clause is executed if the select list was not active or no items remained to be read. The var variable will be set to a null string.
The STATUS() function will return zero unless the ON ERROR clause is executed.
Exploded Select Lists
QM supports two styles of select list; a standard list and an exploded list.
A standard select list contains only simple data, usually record ids. The optional val.pos and subval.pos items are always returned as zero with this type of list.
An exploded select list is created using the BY.EXP or BY.EXP.DSND keywords of the query processor to break apart multi-values and subvalues in a field. Each entry contains the record id together with the value and subvalue position corresponding to the data element associated with the list entry
The optional val.pos and subval.pos components of the READNEXT statement can be used to retrieve this positional data. There are three possible formats: If both are present, the value and subvalue positions are returned in these variables. Where the value was not subdivided into subvalues, the subvalue position is returned as zero. If only val.pos is present, the value position is returned and any subvalue information is discarded. If neither is present, normally only the record id is returned, however, if the program is compiled with the COMPOSITE.READNEXT option of the $MODE compiler directive in force, the data returned in var is made up from the record id, the value position and the subvalue position separated by value marks.
Example
SELECT STOCK.FILE LOOP READNEXT ID PRINT ID REPEAT
This program fragment produces a list of the record keys present in STOCK.FILE. |