READLIST

The READLIST statement reads a select list into a dynamic array.

Format

READLIST var {FROM list.no}

{THEN statement(s)}

{ELSE statement(s)}

where

var	is the variable to receive the select list.

list.no

is the select list number. If omitted, select list zero is used. A Pick style select list variable may be used instead of a list number.

statement(s)

are statement(s) to be performed depending on the outcome of the READLIST operation.

The THEN and ELSE clauses are both optional. If neither is given, the program can recognise failure by var being a null string.

The specified select list is read into var. If the list had already been partially processed by READNEXT statements, only the remaining unprocessed items are stored in var.

The select list is empty after the READLIST statement is completed.

The THEN clause is executed if var contains one or more items. Items are separated by field marks. If compatibility with other software is required, it is suggested that programs should be written to accept either field marks or item marks (or a mix) as list separators.

The ELSE clause is executed if the select list was not active or if no items remained to be processed. In this case var will be set to a null string.

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. 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 in the select list contains four values corresponding to the record id, the value, subvalue and field positions corresponding to the data element associated with the list entry. The READLIST statement will return this composite data.

Example

READLIST S FROM 2 THEN

WRITE S TO LISTS, "UNPROCESSED"

END

This program fragment retrieves the remaining items in select list 2 and, if there are any, writes them to a record UNPROCESSED in file LISTS.