EXTRACT

Caché MultiValue Basic Reference

EXTRACT

Server:docs1

Instance:LATEST

User:UnknownUser


	[ Home ] > [ MultiValue Features of Caché ] > [ Caché MultiValue Basic Reference ] > [ Caché MultiValue Basic Functions ] > [ EXTRACT ]		Go to:		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.