READNEXT

READNEXT

Top  Previous  Next

 

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

 

varis the variable to receive the select list item.

 

val.posis the variable to receive the value position with an exploded select list.

 

subval.posis the variable to receive the subvalue position with an exploded select list.

 

list.nois the select list number. If omitted, the default select list is used. The READNEXT statement can also use select list variables returned by the SELECTV statement or the RTNLIST option of the EXECUTE statement.

 

statement(s)are statement(s) to be executed depending on the outcome of the READNEXT operation.

 

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 unless the PICK.READNEXT setting of the $MODE compiler directive is active, in which case the variable is left unchanged.

 

The STATUS() function will return zero unless the ON ERROR clause is executed.

 

 

Migration Note

 

Some other multivalue products leave var unchanged if the ELSE clause is taken. Use of the PICK.READNEXT setting of the $MODE compiler directive gives this behaviour.

 

 

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 multivalues 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 ELSE EXIT

  PRINT ID

REPEAT

 

This program fragment produces a list of the record keys present in STOCK.FILE.