Creates an array at a specified AN. 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
INTArrayCreateByAn(INT nAN, INT x [, INT y [, INT z]])
hAN:
The AN number to associate with the array.
Elements in a Genie can access array cell values associated with a particular AN number without having the array handle. The Genie creates the array and associates it with the AN of one of the items in the Genie when it is initialized or the page is created. Other items in the Genie can then get or set values in that array. The List View Genie uses this ‘ByAn’ array feature.
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 ArrayDestroyByAn).
Related Functions
ArrayCreate, ArrayCopy, ArrayDestroy, ArrayDestroyByAn, ArrayExists, ArrayExistsByAn, ArrayFillFromAlarmDataByAn, ArrayGetArrayByAn, ArrayGetInfo, ArrayGetInt, ArrayGetIntByAn, ArrayGetMapName, ArrayGetMapNameByAn, ArrayGetString, ArrayGetStringByAn, ArrayIsDirty, ArraySetInt, ArraySetIntByAn, ArraySetIsDirty, ArraySetString, ArraySetStringByAn, ArraySwap, DspArrayByAn
Example
... hArray = ArrayCreateByAn(hAn, 128, 128, 128); err0 = IsError(); // error = 0 - number of elements 2,097,152 hArray = ArrayCreateByAn(hAn, 129, 128, 128); err1 = IsError(); // error = 272 out of memory hArray = ArrayCreateByAn(hAn, 128, 128, 129); err2 = IsError(); // error = 272 out of memory hArray = ArrayCreateByAn(hAn, 32765, 1, 1); err3 = IsError(); // error = 0 hArray = ArrayCreateByAn(hAn, 32765, 10, 5); err4 = IsError(); // error = 0 - number of elements 1,638,250 hArray = ArrayCreateByAn(hAn, 32766, 1, 1); err5 = IsError(); // error = 257 - value is out of range hArray = ArrayCreateByAn(hAn, 1, 32766, 1); err6 = IsError(); // error = 257 - value is out of range hArray = ArrayCreateByAn(hAn, 1, 1, 32766); err7 = IsError(); // error = 257 - value is out of range hArray = ArrayCreateByAn(hAn, 3, 3, 3); err8 = IsError(); // error = 0 ...
See Also
Published June 2018