# 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.

- 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.

```
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);`

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

- 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:`

- These statements are not valid because TEAMS is an array data
structure. A non-array key subfield must be specified.
`SORTA TEAMS; SORTA TEAMS(*);`

- 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(*);`

- This statement is not valid because TEAMS(*).EMPS(*) specifies
two different arrays to be sorted. Only one (*) may be specified.
`SORTA TEAMS(*).EMPS(*).NAME;`

- 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;`

- 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;`

- These statements are not valid because TEAMS is an array data
structure. A non-array key subfield must be specified.