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

Reads the previous field id from a select list.
Synopsis
READPREV 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 not specified, 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 READPREV statement reads successive field identifiers from a select list in reverse order, one field identifier per invocation. The field identifier is read from the slist select list into the fieldval variable. Optionally, READPREV can be used to read successive values or successive subvalues within a field (in reverse order), by specifying a multilevel fieldval variable.
READPREV reads the previous field identifier in a select list. READNEXT reads the next field identifier in a select list.
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. READPREV executes the THEN clause if the select list pointer has not reached the beginning of the select list. The THEN clause is executed even when a field identifier is the null string. READPREV executes the ELSE clause if the select list pointer has reached the beginning 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.
If READPREV reaches the beginning of the select list, it clears the select list. For this reason, a subsequent READNEXT cannot read the first item on the select list. Similarly, if a READNEXT reads the last item of a select list, the list is cleared. A subsequent READPREV cannot be used to read backwards from the end of the select list.
READPREV and READNEXT read 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. READLIST does not clear the select list. Therefore, you can follow a READLIST with a READPREV to read the last field identifier in the select list.
Examples
The following example illustrates the use of the READPREV statement. SELECT copies all of the field mark identifiers into Select List 4. READNEXT reads the next field mark identifier from Select List 4 into the area variable. READPREV reads the previous 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"
READNEXT area FROM 4
  PRINT area;  ! returns "Northeast"
READNEXT area FROM 4
  PRINT area;  ! returns "Southeast"
READPREV area FROM 4
  PRINT area;  ! returns "Northeast"
The following example uses READLIST to advance to the end of the select list, and then uses READPREV to read the last item in the select list:
regions="Northeast":@FM:"Southeast":@FM:"Northwest":@FM:"Southwest"
SELECT regions TO 4 ON ERROR PRINT "Select failed"
READLIST area FROM 4
  PRINT area;  ! returns "Northeast^Southeast^Northwest^Southwest"
READPREV area FROM 4
  PRINT area;  ! returns "Southwest"
See Also