Arrays

General

To arrange data fields of the same type and length, you can use arrays. In LION, arrays consist of up to 6 dimensions. An array element is filled with characters until the maximal number of characters for that element is reached. If the input for an array element exceeds the maximal number of characters, the characters that do not fit will not be stored in the array elements.

All values in an array element are indexed uniquely. Because of this, it is allowed to store the same value in more than one element. The first element in a dimension gets the index number "1", the second element gets index number "2", etc.

Arrays are static, so the maximal number of elements that a dimension can contain and the maximal number of characters for a value in an element are predefined by the programmer and cannot be changed afterwards. Arrays can also be defined in a structure. In that case, the total number of elements that is defined in the subarrays cannot exceed the maximal number of elements that is defined for the structure.

You define an array by using the following syntax, which is similar to definitions for constants, variables or boolean functions:

<Array name> : <Type> <Element size> <Array dimensions>

Item	Description
<Array name>	Name of an array.
<Type>	Types of the values to be stored in the array, e.g. alpha, boolean, etc.
<Element size>	Maximal number of characters that can be put in the array element.
<Array dimensions>	Array dimensions, written as [<Dimension 1>[,<Dimension 2> [,<Dimension 3>[,<Dimension 4>[,<Dimension 5>[,<Dimension 6>].

Array assignments can be written to fill all elements at once, or to fill only one or a selection of element(s).

RESOK

Data Items

For arrays of global and local data items RESOK will always be set, when the arrays is accessed, depending on the index being in or out of bounds.

Index is in bounds: RESOK will be set to TRUE
Index is out of bounds: RESOK will be set to FALSE

Layout Fields with Occurs

Layout fields with Occurs are accessed in the same manner as arrays of data items (for fields with both horizontal and vertical occurs the array will be two dimensional).

<Layout Field>[<Index>] := <Value> or <Value> := <Layout Field>[<Index>]

The RESOK behaviour differs from the behaviour with normal data items:

Index is in bounds: RESOK will be left unchanged
Index is out of bounds: RESOK will be set to false

RESOK Matrix

	Within bounds:	Out of bounds:
Global, local or data items:	RESOK = TRUE	RESOK = FALSE
Layout controls:	RESOK retains current value.	RESOK = FALSE

Remarks

When accessing an array out of bounds, a dummy element will be returned. Every array dimension has one single dummy element, this dummy element will have the same initial value as normal elements. Assigning a value to any out of bounds element in the same array dimension will cause the dummy element to be assigned that value.

Alternatively AMT can be configured so that an exception is raised when trying to access an array out of bounds, this is achieved by the setting 'Exception on array out of bounds' in the 'Runtime behaviour'.


Large arrays take up a lot of memory, especially arrays of strings. On a 64 bit platform each string element will take about 34 bytes of overhead excluding the length of the strings itself. On a 32 bit platform this value is 30 bytes per element.

Examples:

{* With the following line an array is created with the name
'SA_ARRAY'. This array consists of 2 dimensions. The 1st dimension
contains 10 elements. The 2nd dimension contains 2 elements.
The values for these elements can contain 5 characters at most. *}
sa_array : alpha 5 [10, 2]

// An array with character based values is initialized like this:
sa_array [ ] := ' '

// An array with numeric based values is initialized like this:
sa_array [ ] := 0

{* With the following line, the value that is stored as the 5th
element of the first dimension and the 1st element of the 2nd
dimension of the array 'SA_ARRAY' is set to '12345'. If the array
is defined like in the 1st example, the sixth character is omitted,
because the array contains only values up to 5 characters. *}
sa_array[5, 1] := '123456'

{* With the following line, the value that is stored in the 5th
element of the first dimension and the 1st element of the
2nd dimension of the array 'SA_ARRAY' is copied to the value that
is stored as the 3rd element of the first dimension and the 2nd
element of the 2nd dimension. *}
sa_array[3, 2] := sa_array[5, 1]

{* With the following code, the 2nd element to the 11th element in
array I will be moved one index number down in the array. *}
loop for j := 1 to 10
    i[j] := i[j+1]
endloop

{* With the following code, the first 10 elements of the array I
will be incremented by 1 *}
loop for j := 1 to 10
    i[j] := j[j] + 1
endloop

// Two examples using ResOk
// Checking out of bounds in an Array
elem[ind] := value
if not ResOk
    sme('Index out of bounds!')
endif

// Checking out of bounds on a screen control with Occurs
ReSok := true
scrncntrl[ind] := value
if not ResOk
    sme('Index out of bounds!')
endif

Initial Values

When setting the initial values all the elements can be set to the same value using the syntax:

<Array name> : <Type> <Element size> <Array dimension> values all <value>

'values all' works for all arrays except for structure arrays.

The elements of an array can be set individually to an initial value using the syntax:

<Array name> : <Type> <Element size> <Array dimension> values (<value1>, <value2>, ... )

'values (,,...)' works only for one dimensional arrays, and not for structure arrays.

When setting the initial values individually for each element ALL the elements should be set to a value.

Examples:

num-array : numeric 8 [5] values all 123
num-array2 : numeric 8 [5] values (1, 2, 3, 4, 5)