ArrayCreate

Creates an array. An array can include up to 2,097,153 elements, but each dimension needs to have less than 32765.

A Plant SCADA project will only support up to 32765 arrays.

Note: Very large arrays may require a lot of memory. You need to calculate how much memory will be used by an array. For example, an array of 100 x 100 x 100 storing a 100 character string value in each cell will use approximately 100,000,000 bytes of memory.

Syntax

INT ArrayCreate(STRING sArrayName, INT x [, INT y [, INT z]])

sArrayName:

The name of the array.

x:

The size of the array's x–dimension (from 1 to 32765).

y:

The size of the array's y–dimension (from 1 to 32765). This value is optional. If not specified, it defaults to 1.

z:

The size of the array's z–dimension (from 1 to 32765). This value is optional. If not specified, it defaults to 1.

Return Value

The handle of the array. If unsuccessful, –1 is returned. The error code can be obtained by calling the IsError Cicode function.

Note: Any arrays that are created in custom Cicode should also be destroyed in custom Cicode, otherwise the program may eventually consume all available memory (see ArrayDestroy).

Related Functions

ArrayCopy, ArrayCreateByAn, ArrayDestroy, ArrayDestroyByAn, ArrayExists, ArrayExistsByAn, ArrayFillFromAlarmDataByAn, ArrayGetArrayByAn, ArrayGetInfo, ArrayGetInt, ArrayGetIntByAn, ArrayGetMapName, ArrayGetMapNameByAn, ArrayGetString, ArrayGetStringByAn, ArrayIsDirty, ArraySetInt, ArraySetIntByAn, ArraySetIsDirty, ArraySetString, ArraySetStringByAn, ArraySwap, DspArrayByAn

Example

...

hArray = ArrayCreate("TestArray", 128, 128, 128);
err0 = IsError(); // error = 0 - number of elements 2,097,152

hArray = ArrayCreate("TestArray", 129, 128, 128);
err1 = IsError(); // error = 272 out of memory

hArray = ArrayCreate("TestArray", 128, 128, 129);
err2 = IsError(); // error = 272 out of memory

hArray = ArrayCreate("TestArray", 32765, 1, 1);
err3 = IsError(); // error = 0

hArray = ArrayCreate("TestArray", 32765, 10, 5);
err4 = IsError(); // error = 0 - number of elements 1,638,250

hArray = ArrayCreate("TestArray", 32766, 1, 1);
err5 = IsError(); // error = 257 - value is out of range

hArray = ArrayCreate("TestArray", 1, 32766, 1);
err6 = IsError(); // error = 257 - value is out of range

hArray = ArrayCreate("TestArray", 1, 1, 32766);
err7 = IsError(); // error = 257 - value is out of range

hArray = ArrayCreate("TestArray", 32765);
err8 = IsError(); // error = 0

...

See Also

Array Functions