Array Data Structures

An "Array Data Structure" is a data structure defined with keyword DIM. An array data structure is like a multiple-occurrence data structure, except that the index is explicitly specified, as with arrays.

A "Keyed Array Data Structure" is an array data structure with one subfield identified as the search or sort key. The array data structure is indexed by (*) and followed by the specification of the key subfield.

An array data structure can be sorted using the SORTA (Sort an Array) operation code.

The array can be sorted using one of the subfields as a key, by specifying the DS(*).KEY syntax.
The array can be sorted using more than one subfield as a key, by specifying %FIELDS to list the required subfields.

An array data structure can be searched using the %LOOKUP built-in function.The array is searched using one of the subfields as a key.

You can find the element of an array data structure with the maximum or minimum value for one of the subfields by using the %MAXARR or %MINARR built-in functions.

You can choose any subfield to be the key for a particular SORTA operation code or %LOOKUP built-in function. For example, if the ORDERS data structure array has subfields ID and PRICE, you could sort the data structure using the ID subfield as a key, and then you could sort the data structure using the PRICE subfield as a key.

For example, consider array data structure FAMILIES with scalar subfields NAME and NUM_CHILDREN, and an array subfield CHILDREN.

DCL-DS families QUALIFIED DIM(10);
   name VARCHAR(25);
   num_children INT(10);
   DCL-DS children DIM(5);
      name VARCHAR(25);
      age INT(10);
   END-DS;
END-DS;

To use the FAMILIES data structure as an array data structure keyed by NAME, specify FAMILIES(*).NAME.
```
SORTA families(*).name;
IF %LOOKUP('Smith' : families(*).name);
   ...
ENDIF;
```
To sort the FAMILIES array by NUM_CHILDREN and also by NAME if the NUM_CHILDREN values are the same, specify %FIELDS listing NUM_CHILDREN first and NAME second.
```
SORTA FAMILIES %FIELDS(NUM_CHILDREN : NAME);
```
To sort the CHILDREN array subfield of one FAMILIES element by the AGE subfield, use FAMILIES(I).CHILDREN(*).AGE.
```
FOR i = 1 to %ELEM(families);
   SORTA families(i).children(*).age;
ENDFOR;
```
To search the FAMILIES array by the AGE of the first CHILDREN element, use FAMILIES(*).CHILDREN(1).NAME.
```
family = %LOOKUP(10 : families(*).children(1).age);
```

For more examples of array data structures, see

The SORTA operation code
The %LOOKUP built-in function
The %MAXARR and %MINARR built-in functions

Note:

Keyword DIM is only allowed for data structures defined as QUALIFIED.
When keyword DIM is coded for a data structure or LIKEDS subfield, array keywords CTDATA, FROMFILE, and TOFILE are not allowed. In addition, the following data structure keywords are not allowed for an array data structure:
- DTAARA
- OCCURS.
For a data structure X defined with LIKEDS(Y), if data structure Y is defined with keyword DIM, data structure X is not defined as an array data structure.
If X is a subfield in array data structure DS, then an array index must be specified when referring to X in a qualified name. In addition, the array index may not be * except in the context of a keyed array data structure. Within a fully qualified name expression, an array index may only be omitted (or * specified) for the right-most name.
Here are some examples of statements using keyed array data structure expressions that are not valid. Assume that TEAMS is an array data structure with scalar subfield MANAGER and array data structure subfield EMPS.
```
DCL-DS teams QUALIFIED DIM(10);
   manager VARCHAR(25);
   DCL-DS emps DIM(20);
      name VARCHAR(25);
      salary PACKED(7 : 2);
   END-DS;
END-DS:
```
1. These statements are not valid because TEAMS is an array data structure. A non-array key subfield must be specified.
```
   SORTA TEAMS;
   SORTA TEAMS(*);
```
2. These statements are not valid because TEAMS(1).EMPS is an array data structure. A non-array key subfield must be specified.
```
   SORTA TEAMS(1).EMPS;
   SORTA TEAMS(1).EMPS(*);
```
3. This statement is not valid because TEAMS(*).EMPS(*) specifies two different arrays to be sorted. Only one (*) may be specified.
```
   SORTA TEAMS(*).EMPS(*).NAME;
```
4. These statements are not valid because all arrays in the qualified name must be indexed. Both the TEAMS and the EMPS subfields must be indexed; one must be indexed with (*).
```
   SORTA TEAMS(*).EMPS.NAME;
   SORTA TEAMS.EMPS(*).NAME;
```
5. This statement is not valid because at least one array must be indexed by (*). TEAMS(1).EMPS(1).NAME is a scalar value.
```
   SORTA TEAMS(1).EMPS(1).NAME;
```