READLIST
Synopsis
READLIST dynarray FROM slist [THEN statements] [ELSE statements] READLIST dynarray FROM listname [account] [THEN statements] [ELSE statements]
Arguments
| dynarray | A dynamic array used to receive the field values from the select list. |
| slist | An active select list, identified by number or name. A numbered select list is specified as an integer from 0 through 10. A named select list is specified as a variable name. |
| listname account | A saved select list, identified by its assigned listname record ID. If the saved select list is in the current account, omit account. If the saved select list is in another account, specify the account name, separating listname and account with a space character. |
Description
The READLIST statement reads all remaining field identifiers from a select list into a dynamic array. If no reads have been performed on the select list, READLIST reads the entire select list into dynarray. If a READNEXT has been performed on the select list, READLIST reads the remaining select list field identifiers into dynarray.
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.
The listname select list is saved in the &SAVEDLISTS& file. Caché stores this file using the ^SAVEDLISTS global.
The dynarray variable must be simple variable name. It cannot include a system variable, an EQUATE, a dynamic array reference, or a substring reference.
If an error occurs during READLIST processing, Caché sets the dynarray variable to the null string ("").
You can optionally specify a THEN clause, an ELSE clause, or both a THEN and an ELSE clause. If the select list pointer has not reached the end of the select list, READLIST executes the THEN clause. The THEN clause is executed even when all remaining field identifiers are the null string. READLIST 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.
Unlike READNEXT and READPREV, READLIST does not clear the select list when it reaches the end of the select list. For this reason, you can follow a READLIST statement with a READPREV to read individual field identifiers backwards from the end of the select list.
Examples
The following example illustrates the use of the READLIST statement. SELECT copies all of the field mark identifiers into Select List 4. A READNEXT reads the first field mark identifier from Select List 4 into the area variable. A READLIST then reads all the remaining field mark identifiers from Select List 4 into the dynarea dynamic array:
regions="Northeast":@FM:"Southeast":@FM:"Northwest":@FM:"Southwest"
SELECT regions TO 4 ON ERROR PRINT "Select failed"
READNEXT area FROM 4 THEN PRINT area ELSE PRINT "no fields"
! returns "Northeast"
READLIST dynarea FROM 4 THEN PRINT dynarea ELSE PRINT "no fields"
! returns "SoutheastfNorthwestfSouthwest"
READLIST dynarea FROM 4 THEN PRINT dynarea ELSE PRINT "no fields"
! returns "no fields"
