%ELEM (Get Number of Elements)

%ELEM(table_name)
%ELEM(array_name)
%ELEM(multiple_occurrence_data_structure_name)
%ELEM(array_name:*ALLOC)
%ELEM(array_name:*KEEP)
%ELEM(array_name:*MAX)

%ELEM returns the number of elements in the specified array, table, or multiple-occurrence data structure. The value returned is in unsigned integer format (type U). It may be specified anywhere a numeric constant is allowed in the definition specification or in an expression in the extended factor 2 field.

The parameter must be the name of an array, table, or multiple occurrence data structure.

When the array has a variable dimension (the array is defined with DIM(*AUTO) or DIM(*VAR), %ELEM can be used in several additional ways.

%ELEM can be used as the target of an assignment statement to change the current number of elements of the varying-dimension array.
A second parameter can be specified for %ELEM when %ELEM is used for its value.

*ALLOC

The number of elements allocated to the array is returned.

*MAX

The maximum number of elements for the array is returned.
A second parameter can be specified for %ELEM when %ELEM is the target of an assignment statement.

*ALLOC

The number of elements allocated to the array is increased if the value on the right-hand side of the assignment statement is greater than the current number of elements of the array. The number of elements is not changed if the value is less than the current number of elements. The number of elements allocated to the array might be larger than the specified value. The current number of elements is not changed.

*KEEP

The value of any new elements in the array is not changed.

See Varying-dimension arrays.

If the parameter is a complex-qualified name and the data structures containing the required subfield are arrays, then the parameter may be specified in one of two ways:

With indexes specified for all of the data structure arrays in the complex qualified name.
With indexes specified for none of the data structure arrays in the complex qualified name.

See %ELEM Example with a Complex Data Structure.

For more information, see Array Operations or Built-in Functions.

Figure 1. %ELEM Example

 *..1....+....2....+....3....+....4....+....5....+....6....+....7...+....
D*Name++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++
D arr1d           S             20    DIM(10)
D table           S             10    DIM(20) ctdata
D mds             DS            20    occurs(30)
D num             S              5p 0

 * like_array will be defined with a dimension of 10.
 * array_dims will be defined with a value of 10.
D like_array      S                   like(arr1d) dim(%elem(arr1d))
D array_dims      C                   const (%elem (arr1d))

 /FREE
    num = %elem (arr1d);  // num is now 10
    num = %elem (table);  // num is now 20
    num = %elem (mds);    // num is now 30
 /END-FREE

%ELEM Example with a Complex Data Structure

In the following example, the standard way to reference the complex qualified subfield PET is


family(x).child(y).pet

When specified as the parameter for %ELEM, it can be specified either with no indexes specified for the data structure arrays, as in statement 1 or with all indexes specified for the data structure arrays, as in statement 2 .


   DCL-DS family QUALIFIED DIM(3);
      name VARCHAR(25);
      numChildren INT(10);
      DCL-DS child DIM(10);
         name VARCHAR(25);
         numPets INT(10);
         pet VARCHAR(100) DIM(3);
      END-DS;
   END-DS;
   DCL-S x INT(10);

   x = %ELEM(family.child.pet);        //  1 

   x = %ELEM(family(1).child(1).pet);  //  2