Fields - dimensions ¶

Contents

Fields - dimensions

field_id, [”heading”], type & size [[dim1 [, dim2 | [, dim3 [, dim4]]]]] \

[/logical] [,”format” [, flags [, “validation”]]]

Temporary fields may, optionally, be allocated up to four dimensions. These are enclosed in square brackets immediately after the type and size. A dimension list is not preceded by a comma as it is considered to be part of the type & size specification.

Data dictionary fields may be subscripted in one dimension only.

EXAMPLE

a20[5]	A simple array of five alphanumeric 20-byte fields.
i4[10,10]	A two-dimensional array, with 100 4-byte integer elements.
u2[6,6,6]	Three dimensions.
a1[9,9,9,9]	Four dimensions.

Note

Key fields in data files cannot be subscripted.

Accessing elements of dimensioned fields ¶

Elements in dimensioned fields can be accessed in a program in two ways.

Explicitly, by specifying the element required:
```
print tmp.Array[4,4]
```
Implicitly, by omitting the element list:
```
print tmp.Array
```
In this case the program refers to the values of the Sculptor system variables which indicate the current default element for each dimension; in this case, sys.Col and sys.Row. These are explained in full below.

Variables storing default subscript values ¶

Four special Sculptor system variables exist for the purpose of storing the current default subscript for each dimension. They are of type u2. They are all initialised to 1 when a program loads. They may be updated directly, or by use of one of a set of related commands (see table below).

Dimension	Variable	Command
1	sys.Col \| sys.Row	setcol \| setrow
2	sys.Row	setrow
3	sys.Plane	setplane
4	sys.Dim4	setdim4

The variables used differ according to whether the array is dimensioned singly or multiply.

The default subscript for one-dimensional arrays is sys.Row, which may set by direct assignment, or by use of the setrow command.

In multi-dimensional arrays (those with two or more dimensions), sys.Row becomes the default subscript for the second dimension, with sys.Col the default for the first.

Note: Since Sculptor version 6.2.0 they may be 0. But setting one of the above system variables to a value != 0, and accessing then an array field, the rest is automatically initialised to 1.

Assigning two field arrays ¶

Since Sculptor version 6.2.0 when sys.Col, sys.Row, sys.Plane and sys.Dim4 are set to 0 and we assign two field arrays (fldArr1 = fldArr2) we copy the whole array contents, e.g:

!temp i4ArrOrg,,i4[4,4,4,4]
!temp i4ArrDst,,i4[4,4,4,4]

/* Remove the default sys.col... */
sys.Col = 0
sys.Row = 0
sys.Plane = 0
sys.Dim4 = 0

/* Now assign all the array at once */
i4ArrDst = i4ArrOrg

Auto-resizeable field flag ¶

Since Sculptor version 6.2.0 the flag a applied to an array field makes that field eligible for automatic redimension, which means than in certain cases (see below) the dimension sizes of the array will be automatically changed to the assigned value dimension size. The flag can also be specified dynamically with the field flags attribute, these are the ways to specify it:

!temp fld,,i4[2],,a

Or:

!temp fld,,i4[2]
fld->flags = "a"

The cases where an array can be automatically adjusted are:

When assigning a record(rec1) to another record(rec2), any array field of rec1 with the a flag will be redim’ed to the size of the same named array fields on rec2, e.g:
```
!record rec1 {
    fldArray,,a10[2],,a
    fldArrayNoRedim,,a10[2]
}

!record rec2 {
    fldArray,,a10[10]
    fldArrayNoRedim,,a10[10]
}
rec1 = rec2
```
In this example, rec1.fldArray will be redim’ed to be an a10[10] before copying the contents, but not fldArrayNoRedim.
The same happens when just assigning two field arrays when sys.Col, sys.Row, sys.Plane and sys.Dim4 are set to 0 (Note: when changing only one of these and using it with an array access. The rest is initialised to 1), e.g:
```
!temp fldArray1,,a10[2],,a
!temp fldArray1,,a10[10]
fldArray1 = fldArray2
```
Here fldArray1 will be redim’ed to be an a10[10] before copying the whole contents.
read_json_values, read_xml_values, read_web_json_values and read_web_xml_values when reading a JSON or XML file, stream or web content using any of these functions the dimension of any array fields defined with the a flag is redim’ed to be the size of the read JSON or XML array.
get_cookie_names to increase the field array to fit the number of cookies.
dir to increase the field array to fit the number of filenames returned.