REMOVE statement

Syntax

REMOVE element FROM dynamic.array SETTING variable

Description

Use the REMOVE statement to successively extract dynamic array elements that are separated by system delimiters. When a system delimiter is encountered, the extracted element is assigned to element. The REMOVE statement 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 value corresponding to the system delimiter terminating the element just extracted. The delimiter code settings assigned to variable are 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 supported in the PIOPEN flavor

7

ASCII CHAR(249) - Not supported in the PIOPEN flavor

8

ASCII CHAR(248) - Not supported in the PIOPEN flavor

The REMOVE statement 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 statement does not change the dynamic array.

As each element is extracted from dynamic.array to element, 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 statement 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 = 0).

If an element in dynamic.array is the null value, null is returned for that element.

Unlike the EXTRACT function, the REMOVE statement 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 function for the function equivalent of this statement.

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 and PRINT statements 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 REMOVE FIRST FROM NAME SETTING X PRINT 'X= ':X, 'FIRST= ':FIRST

X= 2   FIRST= MIKE

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

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