Caché MultiValue Basic Reference
REMOVE
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Extracts sequential elements of a dynamic array.
Synopsis
REMOVE value FROM dynarray [AT pos] SETTING delim
Arguments
value A variable used to receive the extracted element value.
dynarray A dynamic array from which successive data values are to be extracted.
AT pos Optional — A variable specifying the initial starting position in dynarray as an integer character count. pos must be specified as a local variable, not as a numeric literal. The AT clause is provided for compatibility with D3 and UniData systems.
delim A local variable that resolves to an integer code for the dynamic array delimiter type. delim must be specified as a local variable, not as a numeric literal. delim can accept a single dynamic array reference (A<i>), a single substring reference (A[s,l]), or a substring reference nested inside a dynamic array reference (A<i>[s,l]).
Description
The REMOVE statement efficiently extracts successive data values from a dynamic array. The extracted element value is placed in the value variable. REMOVE operates on a single dynamic array level; you specify the level delimiter using the delim argument. REMOVE maintains an internal pointer so that repeated calls return successive element values. When the last element value has been extracted, REMOVE sets value to the empty string.
You can use the GETREM function to return the character position in dynarray of the REMOVE pointer.
Note:
The REMOVE statement is identical to the REVREMOVE statement, except that REVREMOVE operates in the reverse direction. The REMOVE function, REMOVE statement, and REVREMOVE statement all share the same pointer. It is incremented by a Remove and decremented by a Revremove.
The delim variable resolves to an integer code with one of the following values:
0 End of file
1 @IM Item Mark CHAR(255)
2 @FM Field Mark CHAR(254)
3 @VM Value Mark CHAR(253)
4 @SM Subvalue Mark CHAR(252)
5 @TM Text Mark CHAR(251)
Examples
The following example successively extracts the first 5 Value Mark elements from a dynamic array:
names="Fred":@VM:"Barney":@VM:"Wilma":@VM:"Betty"
delim=3
FOR x=1 TO 5
   REMOVE val FROM names SETTING delim
   PRINT val
   ! Returns:
   !   Fred
   !   Barney
   !   Wilma
   !   Betty
   !   ""
NEXT
See Also