EXTRACT function

Syntax

EXTRACT (dynamic.array, field# [,value# [,subvalue#] ] )
variable < field# [ ,value# [ ,subvalue#] ] >

Description

Use the EXTRACT function to access the data contents of a specified field, value, or subvalue from a dynamic array. You can use either syntax shown to extract data. The first syntax uses the EXTRACT keyword, the second uses angle brackets.

dynamic.array is an expression that evaluates to the array in which the field, value, or subvalue to be extracted is to be found. If dynamic.array evaluates to the null value, null is returned.

field# specifies the field in the dynamic array; value# specifies the value in the field; subvalue# specifies the subvalue in the value. These arguments are called delimiter expressions. The numeric values of the delimiter expressions determine whether a field, a value, or a subvalue is to be extracted. value# and subvalue# are optional.

Angle brackets used as an EXTRACT function appear on the right side of an assignment statement. Angle brackets on the left side of the assignment statement indicate that a REPLACE function is to be performed (for examples, see the REPLACE function).

The second syntax uses angle brackets to extract data from dynamic arrays. variable specifies the dynamic array containing the data to be extracted. field#, value#, and subvalue# are delimiter expressions.

Here are the five outcomes that can result from the different uses of delimiter expressions:

Case 1:: If field#, value#, and subvalue# are omitted or evaluate to 0, an empty string is returned.
Case 2:: If value# and subvalue# are omitted or evaluate to 0, the entire field is extracted.
Case 3:: If subvalue# is omitted or specified as 0 and value# and field# evaluate to nonzero, the entire specified value in the specified field is extracted.
Case 4:: If field#, value#, and subvalue# are all specified and are all nonzero, the specified subvalue is extracted.
Case 5:: If field#, value#, or subvalue# evaluates to the null value, the EXTRACT function fails and the program terminates with a run-time error message.

If a higher-level delimiter expression has a value of 0 when a lower-level delimiter is greater than 0, a 1 is assumed. The delimiter expressions are from highest to lowest: field, value, and subvalue.

If the EXTRACT function references a subordinate element of an element whose value is the null value, null is returned.

Example

In the following example a field mark is shown by F, a value mark is shown by V, and a subvalue mark is shown by S:

VAR=1:@FM:4:@VM:9:@SM:3:@SM:5:@FM:1:@VM:0:@SM:7:@SM:3
Z=EXTRACT(VAR,1,0,0)
PRINT Z
*
Z=VAR<1,1,1>
PRINT Z
*
Z=EXTRACT(VAR,2,1,1)
PRINT Z
*
Z=VAR<3,2,3>
PRINT Z
*
Z=EXTRACT(VAR,10,0,0)
PRINT Z
*
Z=EXTRACT(VAR,2,2,0)
PRINT Z
*

This is the program output: