MATPARSE Statement

Assigns the elements of a string variable to the variables of a dimensioned array.

Syntax

MATPARSE array{,start{,end}} FROM string{ USING delim-char} {SETTING elements-var}

Syntax Elements

array is the name of a dimensioned array to which the variables are assigned.

start, endare optional starting and ending positions from which to start and stop assigning elements to array. If start is omitted or <= 0, it defaults to 1. If end is omitted, or if it is < 1 or greater than the size of array, assignment continues to the end of array. If start > end and end is >= 0, no operation is performed.

string is a string expression from which data is assigned to the elements of array.

delim-char is a delimiter found between elements of the string-var used to build array. The value of delim-char can be from X'00' to X'FE', and must be enclosed in quotes. If delim-char is omitted or null, the default is an attribute mark. If more than one character is specified, only the first is used.

elements-var is a variable to which is assigned the number of elements of array that are assigned a value from string-var.

Operation

The MATPARSE statement performs the opposite function of the MATBUILD statement.

During the MATPARSE process, each element of string-var is assigned to a successive element of array.  If the size of array is greater than the number of parsed elements of string-var, the remaining elements of array are assigned a null value.  The process terminates when the last element of array has been assigned a value, even if string-var is not exhausted.

No run time error messages are generated.

The MATPARSE statement assumes that array is a vector (one-dimensional array). Refer to the section Array Type in the description of the MATBUILD statement.

Examples

X = "1.2.2.1.2.3.4.4.8.2"
DIM ARR(10)
MATPARSE ARR FROM X USING '.'

Assigns each element of X, separated by a period, to dimensioned array ARR.

A = "THIS IS A TEST FOR YOU."
DIM B(12)
MATPARSE B FROM A USING ' ' SETTING Y
PRINT Y

Assigns the elements of variable A to array B and prints the value 6, the number of elements assigned to array B.

VAR = "3,2,5,9,9,2,8"
DIM ARR(4)
MATPARSE ARR FROM VAR USING ','

Assigns only the first four values of variable VAR to array ARR, because ARR has only four elements.

V1 = "ABC^DEF^GHI^JKL^MNO^PQR"
DIM ARR1(15)
MATPARSE ARR1,5,10 FROM V1

Assigns the values of variable V1 to dimensioned array ARR1, starting with the fifth element of ARR1 and ending with the tenth element.