MATBUILD Statement

Builds a string variable from a dimensioned array.

Syntax

MATBUILD variable FROM array{,start{,end}} {USING delim-char}

Syntax Elements

variable is the name of the destination for data built from elements of array.

array is the name of a dimensioned array containing the elements from which to build the variable.

start, endare the optional starting and ending positions from which to start and stop retrieving elements from array. If start is <= 0, it defaults to 1. If end is <=0 or > the size of array, it defaults to the size of array. If start is > end and end is >= 0, no operation takes place. If end is a negative number, it indicates that assignment should continue through the end of array.

delim-char is a single character to be inserted between elements of array when building variable. delim-char can be any value from hex 00 to hex FE, and must be enclosed in quotes. If omitted or null, it defaults to an attribute mark. If more than one character is specified, only the first is used.

Operation

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

During the MATBUILD process, a string is built and assigned to variable by concatenating all elements of array together, separated by a character. The process terminates when the last element of array has been processed, or when all remaining elements of array are null. That way, variable contains no trailing, null elements.

No run time error messages are generated.

Array Type

The MATBUILD statement assumes that array is a vector (one-dimensional array). For example, if array is dimensioned (5,3), then the statement

MATBUILD VAR FROM ARRAY

produces a variable VAR with 15 attributes. VAR<1> equals ARRAY(1,1), VAR<2> equals ARRAY(1,2), and so forth. If you use start and end positions, it can become complicated. For example:

MATBUILD VAR,4,8 FROM ARRAY

builds variable VAR from ARRAY(2,1) through ARRAY(3,2).

Examples

MATBUILD VAR1 FROM ARRAY1

Builds a string VAR1 from the values of ARRAY1 concatenated together.

DIM ARR(5)

ARR(1) = 'A3'

ARR(2) = 'FE'

ARR(3) = '56'

ARR(4) = 'C7'

ARR(5) = '3D'

.

MATBUILD X FROM ARR,2

Builds the string "FE^56^C7^3D", starting with the second element of ARR through to the end, and assigns it to X.

MATBUILD B FROM ARR USING ','

Builds string B from ARR using a comma as delimiter.  String B contains "A3,FE,56,C7,3D".

DIM Y(4)

Y(1) = 'THIS'

Y(2) = 'IS'

Y(3) = 'A'

Y(4) = 'TEST'

.

MATBUILD SENTENCE FROM Y USING ' '

Takes elements of array Y and builds them into the string SENTENCE with a blank space between each word.