REMOVE function

Syntax

REMOVE (dynamic.array, variable)

Description

Use the REMOVE function to successively extract and return dynamic array elements that are separated by system delimiters, and to indicate which system delimiter was found. When a system delimiter is encountered, the value of the extracted element is returned. The REMOVE function is more efficient than the EXTRACT function for extracting successive fields, values, and so on, for multi-value list processing.

dynamic.array is the dynamic array from which to extract elements.

variable is set to a code corresponding to the system delimiter which terminates the extracted element. The contents of variable indicate which system delimiter was found, as follows:

0

End of string

1

Item mark ASCII CHAR(255)

2

Field mark ASCII CHAR(254)

3

Value mark ASCII CHAR(253)

4

Subvalue mark ASCII CHAR(252)

5

Text mark ASCII CHAR(251)

6

ASCII CHAR(250) (Not available in the PIOPEN flavor)

7

ASCII CHAR(249) (Not available in the PIOPEN flavor)

8

ASCII CHAR(248) (Not available in the PIOPEN flavor)

The REMOVE function extracts one element each time it is executed, beginning with the first element in dynamic.array. The operation can be repeated until all elements of dynamic.array are extracted. The REMOVE function does not change the dynamic array.

As each successive element is extracted from dynamic.array, a pointer associated with dynamic.array is set to the beginning of the next element to be extracted. Thus the pointer is advanced every time the REMOVE function is executed.

The pointer is reset to the beginning of dynamic.array whenever dynamic.array is reassigned. Therefore, dynamic.array should not be assigned a new value until all elements have been extracted (that is, until variable is 0).

If dynamic.array evaluates to the null value, null is returned and variable is set to 0 (end of string). If an element in dynamic.array is the null value, null is returned for that element, and variable is set to the appropriate delimiter code.

Unlike the EXTRACT function, the REMOVE function maintains a pointer into the dynamic array. (The EXTRACT function always starts processing at the beginning of the dynamic array, counting field marks, value marks, and subvalue marks until it finds the correct element to extract.)

See the REMOVE statement for the statement equivalent of this function.

Examples

The first example sets the variable FIRST to the string MIKE and the variable X to 2 (field mark). The second example executes the REMOVE function and PRINT statement until all the elements have been extracted, at which point A = 0. Printed lines are 12, 4, 5, 7654, and 00.

Source Lines

Program Output

FM=CHAR(254) NAME='MIKE':FM:'JOHN':FM X=REMOVE(NAME,FIRST) PRINT 'FIRST = ':FIRST, 'X = ':X

FIRST = 2     X = MIKE

VM=CHAR(253) A = 1 Z=12:VM:4:VM:5:VM:7654:VM:00 FOR X=1 TO 20 UNTIL A=0 A = REMOVE(Z,Y) PRINT 'Y = ':Y, 'A = ':A NEXT X

Y = 3  A = 12
Y = 3  A = 4
Y = 3  A = 5
Y = 3  A = 7654
Y = 0  A = 0