Creates an array. An array can include up to 2,097,153 elements, but each dimension needs to have less than 32765.
A Citect 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, 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
Published June 2018