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

Finds the data value of an element of a dynamic array by delimiter position.
Synopsis
EXTRACT(dynarray,f[,v[,s]])
Arguments
dynarray An expression that resolves to a dynamic array.
f An expression that resolves to an integer specifying the Field level of the dynamic array from which to access the data. Fields are counted from 1.
v Optional — An expression that resolves to an integer specifying the Value level of the dynamic array from which to access the data. Values are counted from 1 within a Field.
s Optional — An expression that resolves to an integer specifying the Subvalue level of the dynamic array from which to access the data. Subvalues are counted from 1 within a Value.
Description
The EXTRACT function returns the data value from one element of a dynamic array. Which element to access is specified by the f, v, and s integers. For example, if f=2 and v=3, this means access the third value from the second field. If f=2 and v is not specified, this means to access the entire second field.
If lower level delimiters exist in dynarray, setting an upper level to 0, the null string, or a non-numeric value is equivalent to setting it to 1.
If lower level delimiters do not exist in dynarray, setting this non-existent lower level to 1, 0, the null string, or a non-numeric value has no effect on retrieving the data value in the level above it.
You can also use the <> operator to extract an element value from a dynamic array. For further details, see the Dynamic Arrays page of this manual.
Examples
The following example uses the EXTRACT function to access the second value from the first field of a dynamic array:
cities="New York":@VM:"London":@VM:
"Chicago":@VM:"Boston":@VM:"Los Angeles"
PRINT EXTRACT(cities,1,2)
    ! Returns: "London"
The following examples all return “London”, because the higher level Field Mark value is equivalent to 1:
cities="New York":@VM:"London":@VM:
"Chicago":@VM:"Boston":@VM:"Los Angeles"
PRINT EXTRACT(cities,1,2)
PRINT EXTRACT(cities,0,2)
PRINT EXTRACT(cities,"",2)
The following examples all return “London”, because the lower Subvalue Mark level does not exist:
cities="New York":@VM:"London":@VM:
"Chicago":@VM:"Boston":@VM:"Los Angeles"
PRINT EXTRACT(cities,1,2,0)
PRINT EXTRACT(cities,1,2,1)
PRINT EXTRACT(cities,1,2,"")
Emulation
UniData systems differ in how they handle f, v, and s arguments set to 0. The $OPTIONS ATTR.0IS1 (“zero is one”) provides support for this UniData feature. UniData systems ignore v and s arguments that are set to a negative number.
See Also