Caché MultiValue Basic Reference
FIELDS
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Returns a dynamic array of substrings, based on a delimiter.
Synopsis
FIELDS(dynarray,delimiter,count[,range])
Arguments
dynarray An expression that resolves to a dynamic array. The source dynamic array from which a dynamic array of substrings is to be extracted.
delimiter An expression that resolves to a single character, specified as a number or a string. This character is used as a delimiter to identify substrings within elements. This character cannot also be used as a data value within dynarray. The delimiter characters used in dynamic arrays are listed in the Dynamic Arrays general concepts page of this manual.
count An expression that resolves to an integer that specifies which substring to return from each element of dynarray. Substrings are separated by a delimiter, and counted from 1. A decimal number is truncated to an integer. A string is parsed as a number until a non-numeric character is encountered. Thus “7dwarves” is parsed as 7. A count value of 0, a negative number, the null string, or a non-numeric string is the same as count=1.
range Optional — An expression that resolves to an integer specifying the number of delimited substrings to return for each element, starting with count. If omitted, the default is 1.
Description
The FIELDS function returns a dynamic array of substrings. Each substring is the nth piece of each element, where the integer n is specified by the count parameter, and substrings are separated by a delimiter character. The delimiter itself is not returned.
If count is 1, FIELDS returns the first piece of each element. This is the piece of the string from the beginning of the element to the first delimiter. If the first character of the element is a delimiter, count=1 returns the null string.
If count is greater than the number of delimited substrings in an element, FIELDS returns the null string for that element.
If you specify a delimiter that is not located in dynarray and count=1, FIELDS returns the entire dynarray as a single element. If count>1, FIELDS returns the null string.
If you specify the null string as a delimiter, FIELDS returns the entire dynarray, regardless of the value of count.
If the optional range argument is set to an integer value greater than 1, that number of sequential delimited substrings is returned as a single string. Delimiters within the string are included. If range is a decimal number, it is truncated to its integer value. Setting range to any value other than a numeric 2 or greater is treated as setting it to 1. If range is larger than the number of remaining substrings in the element, the remaining substrings are returned.
The FIELDS function returns delimited substrings from a dynamic array. The FIELD and GROUP functions can be used to return a delimited substring from a string.
Examples
The following example uses the FIELDS function to return the area code from each telephone number element in an array, using the hyphen (-) as a delimiter:
tele="617-123-4567":@VM:"401-555-4321":@VM:"603-987-6543":@VM:"508-246-8024
areacodes=FIELDS(tele,"-",1)
PRINT areacodes
   ! Returns: 617ý401ý603ý508
See Also