%SUBARR built-in function returns a section of the specified Array starting at Start-index.  The number of elements returned is specified by the optional Num-elements parameter, or, if not specified, the number of elements returned defaults to the remainder of the array.

%SUBARR (Array, Start-index {, Num-elements})

Parts

Array

Required. This parameter must be an array. eg, a standalone field, data structure, or subfield defined as an array. This parameter must not be a table name or procedure call.

Start-index

Required. This parameter must be a numeric value with zero decimal positions. Float numeric values are not allowed. The value must be greater than or equal to 1 and less than or equal to the number of elements of the array.

Num-elements

Optional. If specified, this parameter must be a numeric value with zero decimal positions. A float numeric value is not allowed. The value must be greater than or equal to 1 and less than or equal to the number of elements remaining in the array after applying the Start-index value. By default, the number of elements returned is the remaining of the Array.

Remarks

Generally %SUBARR is valid in any expression where an unindexed array is allowed, However, %SUBARR cannot be used in the following places:

• as the array argument of built-in function %LOOKUP.
• a parameter passed by reference.

%SUBARR may be used in the following ways:

• On the left-hand side of an assignment using EVAL. This changes the specified elements in the specified array.
• Within the expression on the right-hand side of an assignment using EVAL where the target of the assignment is an array. This uses the values of the specified elements of the array. The array elements are used directly; a temporary copy of the sub-array is not made.
• As parameter of the SORTARR operation.
• Passed by VALUE or by read-only reference (CONST keyword) when the corresponding parameter is defined as an array.
• As the parameter of the %XFOOT function.

Note It is valid to use %SUBARR to assign part of an array to another part of the same array. However, if the source part of the array overlaps the target part of the array, unpredictable results can occur.

See Also

Built-in Function Overview
DCLARRAY
DCLDS
DCLDSFLD
EVAL
SORTARR
%LOOKUP