FIELDS function

Syntax

FIELDS (dynamic.array, delimiter, occurrence [ ,num.substr] )
CALL -FIELDS (return.array, dynamic.array, delimiter, occurrence, 
num.substr )
CALL !FIELDS (return.array, dynamic.array, delimiter, occurrence, 
num.substr )

Description

Use the FIELDS function to return a dynamic array of substrings located between specified delimiters in each element of dynamic.array.

delimiter evaluates to any character, including value and subvalue characters. It marks the start and end of the substring. If delimiter evaluates to more than one character, the first character is used.

occurrence specifies which occurrence of the delimiter is to be used as a terminator. If occurrence is less than 1, 1 is assumed.

num.substr specifies the number of delimited substrings to return. If the value of num.substr is an empty string or less than 1, 1 is assumed. In this case delimiters are returned along with the successive substrings. If delimiter or occurrence does not exist in the string, an empty string is returned, unless occurrence specifies 1. If occurrence is 1 and the specified delimiter is not found, the entire element is returned. If occurrence is 1 and delimiter is an empty string, an empty string is returned.

If dynamic.array is the null value, null is returned. If any element in dynamic.array is the null value, null is returned for that element. If delimiter, occurrence, or num.substr evaluates to the null value, the FIELDS function fails and the program terminates with a run-time error message.

If you use the subroutine syntax, the resulting dynamic array is returned as return.array.

Example

A="000-P-0":@VM:"-H--O-":@SM:"N-I-T":@VM:"BC":@SM:"-
L-"
PRINT FIELDS(A,"-",2)

This is the program output:

PVHSIVSL