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

Returns the position of the Remove pointer in a dynamic array.
Synopsis
GETREM(dynarray)
Arguments
dynarray An expression that resolves to a dynamic array. dynarray must be a variable, it cannot be a literal dynamic array string.
Description
The GETREM function returns a positive integer indicating the current position of the remove pointer within a dynamic array. This remove pointer can be explicitly incremented by the SETREM statement, and is automatically incremented/decremented by the REMOVE function, the REMOVE statement, and the REVREMOVE statement. GETREM returns this pointer value. This value is an integer count character position within dynarray.
REMOVE and REVREMOVE extract successive data elements from a dynamic array. They establish a pointer specifying the position for the next extract from that dynamic array. Following a REMOVE operation, GETREM returns the character position, counting from 1, of the delimiter following the extracted data. If the REMOVE attempts to extract data past the end of the dynamic array, GETREM returns the length of the dynamic array, plus 1. Subsequent REMOVE operations do not change this end-of-dynamic-array pointer value.
A REVREMOVE operation decrements this pointer to the delimiter preceding the extracted data. If the REVREMOVE attempts to extract data past the beginning of the dynamic array, GETREM returns 0.
If dynarray has never been accessed by these operations, GETREM returns 0. If dynarray is changed, its pointer is reset to 0. If dynarray is a literal string, GETREM issues a syntax error.
Examples
The following example uses the GETREM function to return the Remove pointer position:
cities="Newark":@VM:"New York":@VM:"Boston"
PRINT cities;      ! returns NewarkvNew YorkvBoston
REMOVE val FROM cities SETTING 3
  PRINT val;          ! Returns "Newark"
  PRINT GETREM(cities);    ! returns 7
REMOVE val FROM cities SETTING 3
  PRINT val;          ! Returns "New York"
  PRINT GETREM(cities);    ! returns 16
REMOVE val FROM cities SETTING 3
  PRINT val;          ! Returns "Boston"
  PRINT GETREM(cities);    ! returns 23
REMOVE val FROM cities SETTING 3
  PRINT val;          ! Returns ""
  PRINT GETREM(cities);    ! returns 23
See Also