SysCAD Documentation - User contributions [en]

Array Class

2026-05-26T15:41:14Z

Rod.Stephenson: /* Member Functions */

[[Category:PGM]] [[Category:Examples]]
{{Navigation|[[PGMs]]|[[Class - Introduction|Classes]]}}
{{User Defined Classes Header Table |currentpage=4}}

----
{{TOC}}
== Description ==

The ARRAY class provides member functions to create a dynamic array and manipulate its elements.
* The user may read in an array from a file. The file may be either a CSV file, created using Excel, or a TXT file, created using a test editor such as Notepad++.
* The user may set constant values into an array when it is declared.

'''Notes:'''
# The initial length of the array is zero.
# '''The array is zero indexed''', i.e. the index of the first element in the array is zero, and NOT 1. Therefore, the final element in an array of length ''n'' will have an index = ''n-1''.
# If the index is out of range (0 <= ''index'' < ''length'') then a runtime "PGM class execution error" will occur and the ARRAY operation will be ignored.
# The Array class allows user to Get / Set ''numeric values'' only. Please see [[StrArray Class]] for getting/setting ''String values''.

== Data Members ==

None

== Member Functions ==
The examples in the table below is based on the following variables and array declarations.

<syntaxhighlight lang="pgm">
STRING ArrayFileName
REAL e, DotProduct
LONG d
BIT OK@, EqualOK@, SortOK@, AddOK@, SubOK@, MultOK@, DivOK@
ARRAY a, b, c, NewA, A1, A2, PreVals, z ;declares array instances
</syntaxhighlight>

{| border="1" cellpadding="5" cellspacing="0"
| width="15%" |'''Call ''' || width="35%" | '''Functionality'''|| width="6%" |'''Return Type ''' || width="25%" |'''Parameters ''' || width="30%" | '''Example'''
|-
||'''SetLen'''(''length'') || Sets the size of the array to ''length'' || || ''length :'' the required length of the array, is of data type INTEGER || a.SetLen(5)
|-
||'''GetLen'''() || The function returns the length of the array. || integer || None || d = a.GetLen()
|-
||'''SetSize'''(''length'') {{Available139|30807}} || Sets the size of the array to ''length''. SetSize() function is an equivalent alternative to SetLen() || || ''length :'' the required size of the array, is of data type INTEGER || a.SetSize(5)
|-
||'''Size'''() {{Available139|30807}} || The function returns the length of the array. Size() function is an equivalent alternative to GetLen(). || integer || None || d = a.Size()
|-
|| '''SetAt'''(''index, value'') || This sets the element of the array, which corresponds to the given ''index'' to the specified ''value''. || || ''index'': the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type, INTEGER. ''value :'' the value to which the specified element, in the array, will be set. This is of data type, REAL.'' || a.SetAt(0, 3) OR: a[0] = 3
|-
||'''GetAt'''(''index'') || This retrieves the value (type real) of the element from the array, which corresponds to the given ''index''. || Real || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. || e = a.GetAt(0) or: e = a[0]
|-
||'''IncAt'''(''Index, value'') || This increases the element of the array by the specified value. || || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. ''value :'' the value to which the specified element, in the array, will be increased. This is of data type REAL.'' || "a.IncAt(3, 10)" is equivalent to: temp = a.GetAt(3) a.SetAt(3, temp + 10)
|-
||'''DecAt'''(''Index, value'') || This decreases the element of the array by the specified value. || || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. ''value :'' the value to which the specified element, in the array, will be decreased. This is of data type REAL.'' || "a.DecAt(3, 5)" is equivalent to: temp = a.GetAt(3) a.SetAt(3, temp - 5)"
|-
||'''Sum'''() || This calculates the sum of all elements in the array. || Real || None || e = a.Sum()
|-
||'''Avg'''() || This calculates the average of all elements in the array. || Real || None || e = a.Avg()
|-
||'''Min'''() || This returns the minimum value of all elements in the array. || Real || None || e = a.Min()
|-
||'''MinIndex'''() || This returns the index of the minimum value in the array. If multiple entries of equal minimum value, the first index is returned. Return value is -1 for empty array. || integer || None || d = a.MinIndex()
|-
||'''Max'''() || This returns the maximum value of all elements in the array. || Real || None || e = a.Max()
|-
||'''MaxIndex'''() || This returns the index of the maximum value in the array. If multiple entries of equal maximum value, the first index is returned. Return value is -1 for empty array. || integer || None || d = a.MaxIndex()
|-
|'''Norm'''() {{Available139|30807}} || This normalises the contents of the array such that the sum is 1. Equivalent to a.OpDiv(a.Sum()). || || None || a.Norm()
|-
|'''Reverse'''() {{Available139|30807}} || This reverses the sequence of all elements in the array. || || None || a.Reverse()
|-
|'''Sort'''(''Ascending/Descending'') || This re-arranges all elements in the array in ascending / descending order. || || 0: Descending order, 1: Ascending order || a.Sort(1)
|-
|'''IsSorted'''(''Ascending/Descending'') || This checks if the array is sorted in ascending / descending order. Returns True if array is sorted in the specified order. || Bit || 0: Descending order, 1: Ascending order || SortOK = a.IsSorted(1)
|-
||
'''Load'''(''arrayfilename'')
||
This creates a new array from a file.
* The first element on each line, of the specified file, is read in as an element of the array, until either an empty line or end-of-file character is reached.
* The function returns the value, True if the file was read or, False if the file was not read.
'''Note:''' if any elements exist in the array, prior to calling '''Load''', these elements will be overridden.''
||
Bit
||
''arrayfileName :'' either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder.
||
ArrayFileName = "c:\SysCAD\array.csv" 
OK = b.Load(ArrayFileName) 
or 
OK = c.Load("$Prj\data.txt")
|-
||
'''Save'''(''arrayfilename'')
||
This saves the array data to a comma separated text file.
* If the specified file exists it is overwritten.
* The function returns, True if the file was saved or, False if the file was not saved.
* This could fail for any file access reason, for example: invalid folder, invalid filename, file access error, file already open in another application, etc.
||
Bit
||
''arrayfileName :'' either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder.
||
OK = a.Save("$Prj\data_output.txt")

|-
||
'''CopyToClipboard'''()
||
This saves the array data to the clipboard.
The function returns the value, True.
||
Bit
||
None
||
OK = a.CopyToClipboard()
|-
||'''SetAll'''(''value'') || This sets all the elements of the array to the specified ''value''. || || ''value :'' the required initialising value. This is of data type REAL.'' || a.SetAll(0)
|-
|'''Scale'''(''value'') || All the elements of the array are scaled by the specified ''value'' (New value = original value * Scale). || || ''value :'' the required scaling factor. This is of data type REAL.'' || a.Scale(2) - Each value of the Array "a" will be increased by factor of 2.
|-
|'''Offset'''(''value'') || All the elements of the array are offset by the specified ''value'' (New value = original value + Offset). || || ''value :'' the required offset value. This is of data type REAL.'' || a.Offset(5) - Each value of the Array "a" will be increased by 5.
|-
|'''Copy'''(''Array'') || All the elements of the specified array are copied into the new array. || || ''Array:'' the name of the array to copy from. This is an ARRAY class.'' || PreVals.Copy(a) - The values in Array "a" are copied into the Array "PreVals".
|-
|'''Append'''(''Array'') {{Available139|30807}} || All the elements of the specified array are added to the end of the existing array. The new length of the array will be the sum of the original length plus the length of the specified array.|| || ''Array:'' the name of the array to append. This is an ARRAY class.'' || PreVals.Append(a) - The values in Array "a" are appended to the end of the Array "PreVals".
|-
|'''AppendItem'''(''value'') {{Available139|30874}} || Increase the length of the array by one with the supplied value. || || ''value:'' the value to which the last element in the array will be set. || a.AppendItem(42)
|-
|'''InsertAt'''(''index'', ''value'') {{Available139|32112}} || Increase the length of the array by one inserting the supplied value at the specified ''index''. || || ''index:'' the zero based index in array where the value must be inserted. Index data type is INTEGER and must be in range for Array length. ''value:'' the value to be set at the new inserted element in the array. || a.InsertAt(0, 42) - Inserts 42 at start of array.
|-
|'''RemoveAt'''(''index'', ''count'') {{Available139|32112}} || Decrease the length of the array by removing ''count'' (or less) values starting at the specified ''index''. || || ''index:'' the zero based index in array where values must be deleted. Index data type is INTEGER and must be in range for Array length. ''count:'' the number of elements to be removed. The value of ''count'' may be large, exceeding the current array length in which case all elements from the specified ''index'' are removed. Count data type is INTEGER. || a.RemoveAt(5, 1) - Removes one element at index 5.
|-
|'''IsEqual'''(''Array'') || This compares the current array with the specified array data, if each element of the array are equal, the function returns the value, True. || Bit || ''Array:'' the name of the array to compare with. This is an ARRAY class.'' || EqualOK = PreVals.IsEqual(a) - The values in array "PreVals" are compared to the values of the Array "a". Returns true if they are equal.
|-
|'''Add'''(''Array'') || This function performs addition between current array and a specified array. New value for each element in current array = value in current array + specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || AddOK = NewA.add(A1) (each element in NewA = NewA + A1)
|-
|'''Sub'''(''Array'') || This function performs subtraction between current array and a specified array. New value for each element in current array = value in current array - specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit ||''Array:'' the name of the specified array. This is an ARRAY class. || SubOK = NewA.Sub(A1) (each element in NewA = NewA - A1)
|-
|'''Mult'''(''Array'') || This function performs multiplication between current array and a specified array. New value for each element in current array = value in current array x specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || MultOK = NewA.Mult(A1) (each element in NewA = NewA * A1)
|-
|'''Div'''(''Array'') || This function performs division between current array and a specified array. New value for each element in current array = value in current array / specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit ||''Array:'' the name of the specified array. This is an ARRAY class. || DivOK = NewA.Div(A1) (each element in NewA = NewA / A1)
|-
|'''CopyAdd'''(''Array1, Array2'') || This function performs addition between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 + array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.''|| AddOK = NewA.CopyAdd(A1, A2) (each element in NewA = A1 + A2)
|-
|'''CopySub'''(''Array1, Array2'') || This function performs subtraction between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 - array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.|| AddOK = NewA.CopySub(A1, A2) (each element in NewA = A1 - A2)
|-
|'''CopyMult'''(''Array1, Array2'') || This function performs multiplication between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 x array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class. || AddOK = NewA.CopyMult(A1, A2) (each element in NewA = A1 * A2)
|-
|'''CopyDiv'''(''Array1, Array2'') || This function performs division between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 / array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.|| AddOK = NewA.CopyDiv(A1, A2) (each element in NewA = A1 / A2)
|-
|'''Inner'''(''Array'') || This returns the Sum of Element i (Current Array * Specified Array). The two arrays must have the same length, otherwise error is returned. || REAL || ''Array:'' the name of the second array. This is an ARRAY class.'' || DotProduct = a.Inner(PreVals)
|-
|'''CircConv'''(''Array'') {{Available139|30613}} || This function performs circular convolution calculation between the current array and a specified array. New value for each element in current array is calculated as the integral of the product of the two arrays after one is reversed and shifted. The values in the current array will be replaced with the new value. The two arrays are expected to have the same length. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || AddOK = NewA.CirConv(A1) (each element in NewA = circular convolution of NewA and A1)
|-
|'''CopyCircConv'''(''Array1, Array2'') {{Available139|30613}} || This function performs circular convolution calculation between two arrays and stores the values in a new array (current array). Value for each element in current array is calculated as the integral of the product of the two arrays after one is reversed and shifted. The two arrays are expected to have the same length. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.''|| AddOK = NewA.CopyCirConv(A1, A2) (each element in NewA = circular convolution of A1 and A2)
|-
|'''SetFromStr'''(''Str s, Str Separ'') {{Available139|35544}}|| This function enables the unpacking of a string into an array, converting each element into a number. It internally utilises the StrToFlt function. The array’s length is determined by the number of items derived from unpacking the string.|| REAL || ''s'' is the string that requires unpacking. ''Separ'' is the separator used within the string ‘s’ to define the divisions. ||x.SetFromStr("35,4,30", ",") will unpack the three numbers into the array ‘x’, resulting in x[0]=35, x[1]=4, and x[2]=30.
|-
|'''CopyToStr'''(''Str Separ'') {{Available139|35544}}|| This function enables the consolidation of a ‘Array’ into a single string. || STRING|| ''Separ'' denotes the delimiter used within the string ‘s’ to demarcate its segments. ||x.CopyToStr(",") will combine the elements of the 'Array' named 'x' into the string "35,4,30".
|-
|'''PushBack'''(''value'') '''PushFront'''(''value'') {{Available140}}|| These methods put ''value'' at the start or end of the array and increase the size. || || ''value'': the value to be set. || Equivalent to InsertAt(0, value)
|-
|'''PopBack'''() '''PopFront'''() {{Available140}}|| These functions return the value at the start or end, and decrease the size. || Real || || If A = [1., 2., 3.], A.PopBack() returns 3.0 After, A = [1, 2]
|-
|'''PushFrontPopBack'''(''value'') '''PushBackPopFront'''(''value'') {{Available140}}|| These functions treat the array as a FIFO queue, adding an item at one end and removing and returning the item at the other end. All items are moved up or down in the array and the size is unchanged || Real || Real || If A = [3., 4., 2.] then A.PushFrontPopBack(7): * returns 2. * A is now [7., 3., 4.]
|}

=== Watch ===

The '''Watch''' keyword can be used to display the Array values in the Access Window.

'''Syntax''':
* Individual elements in the array can be made visible - e.g. "Watch A[2]" or "Watch A@[2]".
* A range of array elements can be made visible - e.g. "Watch A[All,5]" which would show the first 5 elements of the array.
* If the "@" symbol is included, then the array elements will be read only fields in the access window.

=== Array with Constant Values ===

The user may declare an array with a set of constant values. This allows the user to set up an array with known values for direct use. It can be a useful alternative to reading values from a CSV file. Once defined, the contents or size of this constant Array cannot be changed. Where a number is not specified for an entry, 0 is assumed. The contents of the array are not saved as they are defined in the code. From {{Available139|32217||y}}, the list can include system constants (for example NAN or PI), or user defined constants. From {{Available139|32325||y}}, the const keyword should be used, otherwise a load warning (or error) is given.

The syntax is:
<syntaxhighlight lang="pgm">
const ARRAY a = {n1,n2,n3,....} ;Syntax from {{Available139|32325||y}}
ARRAY a = {n1,n2,n3,....} ;Syntax before {{Available139|32325||y}}
;where n1, n2 etc. are real numbers or constants.
;Example
const Array SomePrimes = {2,3,5,7,11,13,17,19,23,29,31,37,41,43,47,53,59,61,67,71}
</syntaxhighlight>

=== Caution ===

Using a GetAt within a SetAt can sometimes fail. This may be for expressions with multiple array references.
<syntaxhighlight lang="pgm">
;For example:
a.SetAt(i, a.GetAt(i+1)) ;This can sometimes fail

;The solution is to use a temporary variable to first retrieve the GetAt value and then call SetAt as follows:
Real Tmp
Tmp = a.GetAt(i+1)
a.SetAt(i, Tmp)
</syntaxhighlight>

== Example ==

<syntaxhighlight lang="pgm">
STRING ArrayFileName
REAL d, e, f, Total@, Average@, Minimum@, Maximum@, DotProduct@
BIT OK@, CopyOK@, SortOK@, AddOK@, SubOK@
ARRAY a ;declares array instance.
ARRAY b{e}, c{e} ;declares array instances that are excluded from save (for efficiency).
const ARRAY x = {60,35,25,62,105} ;declares an array z with constant values.
;ARRAY x = {60,35,25,62,105} ;Old syntax before {{Removed139|32325||y}}
ARRAY y, y1, y2
const ARRAY y3 = {20,35,45,62,105,150} ;declares an array y3 with constant values.
const ARRAY z = {20,35,45,62,105} ;declares an array z with constant values.

Sub InitialiseSolution()
ArrayFileName = "c:\SysCAD\array.csv"
OK = b.Load(ArrayFileName)
OK = c.Load("$Prj\data.txt")
a.SetLen(5) ;sets the array length
y.copy(x) ;array x is copied into array y, returns {60,35,25,62,105}
CopyOK = y.isEqual(x) ;compares array y with array x, returns true
y.sort(1) ;sorts array y in ascending order, returns {25,35,60,62,105}
SortOK = y.IsSorted(1) ;checks if array y is sorted in ascending order, returns true
y1.copy(y) ;copies y, returns {25,35,60,62,105}
y1.scale(2) ;multiplies each element by scaling factor of 2, returns {50, 70, 120, 124, 210}
y2.copy(y) ;copies y, returns {25,35,60,62,105}
y2.offset(5) ;adds each element by offset factor of 5, returns {30, 40, 65, 67, 110}
AddOK = y.add(y2) ;Adds each element of y to elements of y2, y now becomes {55, 75, 125, 129, 215}, returns true
SubOK = y1.sub(y3) ;returns false since array length of y1 does not equal to y3. Array y1 unchanged.
DotProduct = y.inner(y2) ;sum of each element y_i * y2_i, returns 45068
EndSub

;Logic
d = a.GetLen() ;gets the array length
a.SetAll(2.2/2) ;sets all elements
a.IncAt(0, 7.0) ;increments the first element
a[d-1] = 3.3 ;sets last element
e = a[0] ;gets first element
f = z[3] ;gets the fourth element of array z, so f = 62
Total = z.Sum() ;gets the sum of all the values in array z, Total = 267
Average = z.Avg() ;gets the average of all the values in array z, Average = 53.4
Minimum = z.Min() ;gets the minimum of all the values in array z, Minimum = 20
Maximum = z.Max() ;gets the maximum of all the values in array z, Maximum = 105
$
</syntaxhighlight>

See also: [[Python Example - Optimization#Calculating_the_objective_error | Optimisation Example]] shows using these Array tools in a real example for plant tuning calculating an objective function.

Array Class

2026-05-26T15:40:19Z

Rod.Stephenson: /* Member Functions */

[[Category:PGM]] [[Category:Examples]]
{{Navigation|[[PGMs]]|[[Class - Introduction|Classes]]}}
{{User Defined Classes Header Table |currentpage=4}}

----
{{TOC}}
== Description ==

The ARRAY class provides member functions to create a dynamic array and manipulate its elements.
* The user may read in an array from a file. The file may be either a CSV file, created using Excel, or a TXT file, created using a test editor such as Notepad++.
* The user may set constant values into an array when it is declared.

'''Notes:'''
# The initial length of the array is zero.
# '''The array is zero indexed''', i.e. the index of the first element in the array is zero, and NOT 1. Therefore, the final element in an array of length ''n'' will have an index = ''n-1''.
# If the index is out of range (0 <= ''index'' < ''length'') then a runtime "PGM class execution error" will occur and the ARRAY operation will be ignored.
# The Array class allows user to Get / Set ''numeric values'' only. Please see [[StrArray Class]] for getting/setting ''String values''.

== Data Members ==

None

== Member Functions ==
The examples in the table below is based on the following variables and array declarations.

<syntaxhighlight lang="pgm">
STRING ArrayFileName
REAL e, DotProduct
LONG d
BIT OK@, EqualOK@, SortOK@, AddOK@, SubOK@, MultOK@, DivOK@
ARRAY a, b, c, NewA, A1, A2, PreVals, z ;declares array instances
</syntaxhighlight>

{| border="1" cellpadding="5" cellspacing="0"
| width="15%" |'''Call ''' || width="35%" | '''Functionality'''|| width="6%" |'''Return Type ''' || width="25%" |'''Parameters ''' || width="30%" | '''Example'''
|-
||'''SetLen'''(''length'') || Sets the size of the array to ''length'' || || ''length :'' the required length of the array, is of data type INTEGER || a.SetLen(5)
|-
||'''GetLen'''() || The function returns the length of the array. || integer || None || d = a.GetLen()
|-
||'''SetSize'''(''length'') {{Available139|30807}} || Sets the size of the array to ''length''. SetSize() function is an equivalent alternative to SetLen() || || ''length :'' the required size of the array, is of data type INTEGER || a.SetSize(5)
|-
||'''Size'''() {{Available139|30807}} || The function returns the length of the array. Size() function is an equivalent alternative to GetLen(). || integer || None || d = a.Size()
|-
|| '''SetAt'''(''index, value'') || This sets the element of the array, which corresponds to the given ''index'' to the specified ''value''. || || ''index'': the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type, INTEGER. ''value :'' the value to which the specified element, in the array, will be set. This is of data type, REAL.'' || a.SetAt(0, 3) OR: a[0] = 3
|-
||'''GetAt'''(''index'') || This retrieves the value (type real) of the element from the array, which corresponds to the given ''index''. || Real || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. || e = a.GetAt(0) or: e = a[0]
|-
||'''IncAt'''(''Index, value'') || This increases the element of the array by the specified value. || || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. ''value :'' the value to which the specified element, in the array, will be increased. This is of data type REAL.'' || "a.IncAt(3, 10)" is equivalent to: temp = a.GetAt(3) a.SetAt(3, temp + 10)
|-
||'''DecAt'''(''Index, value'') || This decreases the element of the array by the specified value. || || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. ''value :'' the value to which the specified element, in the array, will be decreased. This is of data type REAL.'' || "a.DecAt(3, 5)" is equivalent to: temp = a.GetAt(3) a.SetAt(3, temp - 5)"
|-
||'''Sum'''() || This calculates the sum of all elements in the array. || Real || None || e = a.Sum()
|-
||'''Avg'''() || This calculates the average of all elements in the array. || Real || None || e = a.Avg()
|-
||'''Min'''() || This returns the minimum value of all elements in the array. || Real || None || e = a.Min()
|-
||'''MinIndex'''() || This returns the index of the minimum value in the array. If multiple entries of equal minimum value, the first index is returned. Return value is -1 for empty array. || integer || None || d = a.MinIndex()
|-
||'''Max'''() || This returns the maximum value of all elements in the array. || Real || None || e = a.Max()
|-
||'''MaxIndex'''() || This returns the index of the maximum value in the array. If multiple entries of equal maximum value, the first index is returned. Return value is -1 for empty array. || integer || None || d = a.MaxIndex()
|-
|'''Norm'''() {{Available139|30807}} || This normalises the contents of the array such that the sum is 1. Equivalent to a.OpDiv(a.Sum()). || || None || a.Norm()
|-
|'''Reverse'''() {{Available139|30807}} || This reverses the sequence of all elements in the array. || || None || a.Reverse()
|-
|'''Sort'''(''Ascending/Descending'') || This re-arranges all elements in the array in ascending / descending order. || || 0: Descending order, 1: Ascending order || a.Sort(1)
|-
|'''IsSorted'''(''Ascending/Descending'') || This checks if the array is sorted in ascending / descending order. Returns True if array is sorted in the specified order. || Bit || 0: Descending order, 1: Ascending order || SortOK = a.IsSorted(1)
|-
||
'''Load'''(''arrayfilename'')
||
This creates a new array from a file.
* The first element on each line, of the specified file, is read in as an element of the array, until either an empty line or end-of-file character is reached.
* The function returns the value, True if the file was read or, False if the file was not read.
'''Note:''' if any elements exist in the array, prior to calling '''Load''', these elements will be overridden.''
||
Bit
||
''arrayfileName :'' either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder.
||
ArrayFileName = "c:\SysCAD\array.csv" 
OK = b.Load(ArrayFileName) 
or 
OK = c.Load("$Prj\data.txt")
|-
||
'''Save'''(''arrayfilename'')
||
This saves the array data to a comma separated text file.
* If the specified file exists it is overwritten.
* The function returns, True if the file was saved or, False if the file was not saved.
* This could fail for any file access reason, for example: invalid folder, invalid filename, file access error, file already open in another application, etc.
||
Bit
||
''arrayfileName :'' either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder.
||
OK = a.Save("$Prj\data_output.txt")

|-
||
'''CopyToClipboard'''()
||
This saves the array data to the clipboard.
The function returns the value, True.
||
Bit
||
None
||
OK = a.CopyToClipboard()
|-
||'''SetAll'''(''value'') || This sets all the elements of the array to the specified ''value''. || || ''value :'' the required initialising value. This is of data type REAL.'' || a.SetAll(0)
|-
|'''Scale'''(''value'') || All the elements of the array are scaled by the specified ''value'' (New value = original value * Scale). || || ''value :'' the required scaling factor. This is of data type REAL.'' || a.Scale(2) - Each value of the Array "a" will be increased by factor of 2.
|-
|'''Offset'''(''value'') || All the elements of the array are offset by the specified ''value'' (New value = original value + Offset). || || ''value :'' the required offset value. This is of data type REAL.'' || a.Offset(5) - Each value of the Array "a" will be increased by 5.
|-
|'''Copy'''(''Array'') || All the elements of the specified array are copied into the new array. || || ''Array:'' the name of the array to copy from. This is an ARRAY class.'' || PreVals.Copy(a) - The values in Array "a" are copied into the Array "PreVals".
|-
|'''Append'''(''Array'') {{Available139|30807}} || All the elements of the specified array are added to the end of the existing array. The new length of the array will be the sum of the original length plus the length of the specified array.|| || ''Array:'' the name of the array to append. This is an ARRAY class.'' || PreVals.Append(a) - The values in Array "a" are appended to the end of the Array "PreVals".
|-
|'''AppendItem'''(''value'') {{Available139|30874}} || Increase the length of the array by one with the supplied value. || || ''value:'' the value to which the last element in the array will be set. || a.AppendItem(42)
|-
|'''InsertAt'''(''index'', ''value'') {{Available139|32112}} || Increase the length of the array by one inserting the supplied value at the specified ''index''. || || ''index:'' the zero based index in array where the value must be inserted. Index data type is INTEGER and must be in range for Array length. ''value:'' the value to be set at the new inserted element in the array. || a.InsertAt(0, 42) - Inserts 42 at start of array.
|-
|'''RemoveAt'''(''index'', ''count'') {{Available139|32112}} || Decrease the length of the array by removing ''count'' (or less) values starting at the specified ''index''. || || ''index:'' the zero based index in array where values must be deleted. Index data type is INTEGER and must be in range for Array length. ''count:'' the number of elements to be removed. The value of ''count'' may be large, exceeding the current array length in which case all elements from the specified ''index'' are removed. Count data type is INTEGER. || a.RemoveAt(5, 1) - Removes one element at index 5.
|-
|'''IsEqual'''(''Array'') || This compares the current array with the specified array data, if each element of the array are equal, the function returns the value, True. || Bit || ''Array:'' the name of the array to compare with. This is an ARRAY class.'' || EqualOK = PreVals.IsEqual(a) - The values in array "PreVals" are compared to the values of the Array "a". Returns true if they are equal.
|-
|'''Add'''(''Array'') || This function performs addition between current array and a specified array. New value for each element in current array = value in current array + specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || AddOK = NewA.add(A1) (each element in NewA = NewA + A1)
|-
|'''Sub'''(''Array'') || This function performs subtraction between current array and a specified array. New value for each element in current array = value in current array - specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit ||''Array:'' the name of the specified array. This is an ARRAY class. || SubOK = NewA.Sub(A1) (each element in NewA = NewA - A1)
|-
|'''Mult'''(''Array'') || This function performs multiplication between current array and a specified array. New value for each element in current array = value in current array x specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || MultOK = NewA.Mult(A1) (each element in NewA = NewA * A1)
|-
|'''Div'''(''Array'') || This function performs division between current array and a specified array. New value for each element in current array = value in current array / specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit ||''Array:'' the name of the specified array. This is an ARRAY class. || DivOK = NewA.Div(A1) (each element in NewA = NewA / A1)
|-
|'''CopyAdd'''(''Array1, Array2'') || This function performs addition between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 + array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.''|| AddOK = NewA.CopyAdd(A1, A2) (each element in NewA = A1 + A2)
|-
|'''CopySub'''(''Array1, Array2'') || This function performs subtraction between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 - array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.|| AddOK = NewA.CopySub(A1, A2) (each element in NewA = A1 - A2)
|-
|'''CopyMult'''(''Array1, Array2'') || This function performs multiplication between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 x array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class. || AddOK = NewA.CopyMult(A1, A2) (each element in NewA = A1 * A2)
|-
|'''CopyDiv'''(''Array1, Array2'') || This function performs division between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 / array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.|| AddOK = NewA.CopyDiv(A1, A2) (each element in NewA = A1 / A2)
|-
|'''Inner'''(''Array'') || This returns the Sum of Element i (Current Array * Specified Array). The two arrays must have the same length, otherwise error is returned. || REAL || ''Array:'' the name of the second array. This is an ARRAY class.'' || DotProduct = a.Inner(PreVals)
|-
|'''CircConv'''(''Array'') {{Available139|30613}} || This function performs circular convolution calculation between the current array and a specified array. New value for each element in current array is calculated as the integral of the product of the two arrays after one is reversed and shifted. The values in the current array will be replaced with the new value. The two arrays are expected to have the same length. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || AddOK = NewA.CirConv(A1) (each element in NewA = circular convolution of NewA and A1)
|-
|'''CopyCircConv'''(''Array1, Array2'') {{Available139|30613}} || This function performs circular convolution calculation between two arrays and stores the values in a new array (current array). Value for each element in current array is calculated as the integral of the product of the two arrays after one is reversed and shifted. The two arrays are expected to have the same length. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.''|| AddOK = NewA.CopyCirConv(A1, A2) (each element in NewA = circular convolution of A1 and A2)
|-
|'''SetFromStr'''(''Str s, Str Separ'') {{Available139|35544}}|| This function enables the unpacking of a string into an array, converting each element into a number. It internally utilises the StrToFlt function. The array’s length is determined by the number of items derived from unpacking the string.|| REAL || ''s'' is the string that requires unpacking. ''Separ'' is the separator used within the string ‘s’ to define the divisions. ||x.SetFromStr("35,4,30", ",") will unpack the three numbers into the array ‘x’, resulting in x[0]=35, x[1]=4, and x[2]=30.
|-
|'''CopyToStr'''(''Str Separ'') {{Available139|35544}}|| This function enables the consolidation of a ‘Array’ into a single string. || STRING|| ''Separ'' denotes the delimiter used within the string ‘s’ to demarcate its segments. ||x.CopyToStr(",") will combine the elements of the 'Array' named 'x' into the string "35,4,30".
|-
|'''PushBack'''(''value'') '''PushFront'''(''value'') {{Available140}}|| These methods put ''value'' at the start or end of the array and increase the size. || || ''value'': the value to be set. || Equivalent to InsertAt(0, value)
|-
|'''PopBack'''() '''PopFront'''() {{Available140}}|| These functions return the value at the start or end, and decrease the size. || Real || || If A = [1., 2., 3.], A.PopBack() returns 3.0 After, A = [1, 2]
|-
|'''PushFrontPopBack'''(''value'') '''PushBackPopFront'''(''value'') {{Available140}}|| These functions treat the array as a FIFO queue, adding an item at one end and removing and returning the item at the other end. All items are moved up or down in the array and the size is unchanged || Real || Real || If A = [3., 4., 2.] then A.PushFrontPopBack(7): returns 2. A is now [7., 3., 4.]
|}

=== Watch ===

The '''Watch''' keyword can be used to display the Array values in the Access Window.

'''Syntax''':
* Individual elements in the array can be made visible - e.g. "Watch A[2]" or "Watch A@[2]".
* A range of array elements can be made visible - e.g. "Watch A[All,5]" which would show the first 5 elements of the array.
* If the "@" symbol is included, then the array elements will be read only fields in the access window.

=== Array with Constant Values ===

The user may declare an array with a set of constant values. This allows the user to set up an array with known values for direct use. It can be a useful alternative to reading values from a CSV file. Once defined, the contents or size of this constant Array cannot be changed. Where a number is not specified for an entry, 0 is assumed. The contents of the array are not saved as they are defined in the code. From {{Available139|32217||y}}, the list can include system constants (for example NAN or PI), or user defined constants. From {{Available139|32325||y}}, the const keyword should be used, otherwise a load warning (or error) is given.

The syntax is:
<syntaxhighlight lang="pgm">
const ARRAY a = {n1,n2,n3,....} ;Syntax from {{Available139|32325||y}}
ARRAY a = {n1,n2,n3,....} ;Syntax before {{Available139|32325||y}}
;where n1, n2 etc. are real numbers or constants.
;Example
const Array SomePrimes = {2,3,5,7,11,13,17,19,23,29,31,37,41,43,47,53,59,61,67,71}
</syntaxhighlight>

=== Caution ===

Using a GetAt within a SetAt can sometimes fail. This may be for expressions with multiple array references.
<syntaxhighlight lang="pgm">
;For example:
a.SetAt(i, a.GetAt(i+1)) ;This can sometimes fail

;The solution is to use a temporary variable to first retrieve the GetAt value and then call SetAt as follows:
Real Tmp
Tmp = a.GetAt(i+1)
a.SetAt(i, Tmp)
</syntaxhighlight>

== Example ==

<syntaxhighlight lang="pgm">
STRING ArrayFileName
REAL d, e, f, Total@, Average@, Minimum@, Maximum@, DotProduct@
BIT OK@, CopyOK@, SortOK@, AddOK@, SubOK@
ARRAY a ;declares array instance.
ARRAY b{e}, c{e} ;declares array instances that are excluded from save (for efficiency).
const ARRAY x = {60,35,25,62,105} ;declares an array z with constant values.
;ARRAY x = {60,35,25,62,105} ;Old syntax before {{Removed139|32325||y}}
ARRAY y, y1, y2
const ARRAY y3 = {20,35,45,62,105,150} ;declares an array y3 with constant values.
const ARRAY z = {20,35,45,62,105} ;declares an array z with constant values.

Sub InitialiseSolution()
ArrayFileName = "c:\SysCAD\array.csv"
OK = b.Load(ArrayFileName)
OK = c.Load("$Prj\data.txt")
a.SetLen(5) ;sets the array length
y.copy(x) ;array x is copied into array y, returns {60,35,25,62,105}
CopyOK = y.isEqual(x) ;compares array y with array x, returns true
y.sort(1) ;sorts array y in ascending order, returns {25,35,60,62,105}
SortOK = y.IsSorted(1) ;checks if array y is sorted in ascending order, returns true
y1.copy(y) ;copies y, returns {25,35,60,62,105}
y1.scale(2) ;multiplies each element by scaling factor of 2, returns {50, 70, 120, 124, 210}
y2.copy(y) ;copies y, returns {25,35,60,62,105}
y2.offset(5) ;adds each element by offset factor of 5, returns {30, 40, 65, 67, 110}
AddOK = y.add(y2) ;Adds each element of y to elements of y2, y now becomes {55, 75, 125, 129, 215}, returns true
SubOK = y1.sub(y3) ;returns false since array length of y1 does not equal to y3. Array y1 unchanged.
DotProduct = y.inner(y2) ;sum of each element y_i * y2_i, returns 45068
EndSub

;Logic
d = a.GetLen() ;gets the array length
a.SetAll(2.2/2) ;sets all elements
a.IncAt(0, 7.0) ;increments the first element
a[d-1] = 3.3 ;sets last element
e = a[0] ;gets first element
f = z[3] ;gets the fourth element of array z, so f = 62
Total = z.Sum() ;gets the sum of all the values in array z, Total = 267
Average = z.Avg() ;gets the average of all the values in array z, Average = 53.4
Minimum = z.Min() ;gets the minimum of all the values in array z, Minimum = 20
Maximum = z.Max() ;gets the maximum of all the values in array z, Maximum = 105
$
</syntaxhighlight>

See also: [[Python Example - Optimization#Calculating_the_objective_error | Optimisation Example]] shows using these Array tools in a real example for plant tuning calculating an objective function.

Array Class

2026-05-26T15:34:38Z

Rod.Stephenson: /* Member Functions */

[[Category:PGM]] [[Category:Examples]]
{{Navigation|[[PGMs]]|[[Class - Introduction|Classes]]}}
{{User Defined Classes Header Table |currentpage=4}}

----
{{TOC}}
== Description ==

The ARRAY class provides member functions to create a dynamic array and manipulate its elements.
* The user may read in an array from a file. The file may be either a CSV file, created using Excel, or a TXT file, created using a test editor such as Notepad++.
* The user may set constant values into an array when it is declared.

'''Notes:'''
# The initial length of the array is zero.
# '''The array is zero indexed''', i.e. the index of the first element in the array is zero, and NOT 1. Therefore, the final element in an array of length ''n'' will have an index = ''n-1''.
# If the index is out of range (0 <= ''index'' < ''length'') then a runtime "PGM class execution error" will occur and the ARRAY operation will be ignored.
# The Array class allows user to Get / Set ''numeric values'' only. Please see [[StrArray Class]] for getting/setting ''String values''.

== Data Members ==

None

== Member Functions ==
The examples in the table below is based on the following variables and array declarations.

<syntaxhighlight lang="pgm">
STRING ArrayFileName
REAL e, DotProduct
LONG d
BIT OK@, EqualOK@, SortOK@, AddOK@, SubOK@, MultOK@, DivOK@
ARRAY a, b, c, NewA, A1, A2, PreVals, z ;declares array instances
</syntaxhighlight>

{| border="1" cellpadding="5" cellspacing="0"
| width="15%" |'''Call ''' || width="35%" | '''Functionality'''|| width="6%" |'''Return Type ''' || width="25%" |'''Parameters ''' || width="30%" | '''Example'''
|-
||'''SetLen'''(''length'') || Sets the size of the array to ''length'' || || ''length :'' the required length of the array, is of data type INTEGER || a.SetLen(5)
|-
||'''GetLen'''() || The function returns the length of the array. || integer || None || d = a.GetLen()
|-
||'''SetSize'''(''length'') {{Available139|30807}} || Sets the size of the array to ''length''. SetSize() function is an equivalent alternative to SetLen() || || ''length :'' the required size of the array, is of data type INTEGER || a.SetSize(5)
|-
||'''Size'''() {{Available139|30807}} || The function returns the length of the array. Size() function is an equivalent alternative to GetLen(). || integer || None || d = a.Size()
|-
|| '''SetAt'''(''index, value'') || This sets the element of the array, which corresponds to the given ''index'' to the specified ''value''. || || ''index'': the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type, INTEGER. ''value :'' the value to which the specified element, in the array, will be set. This is of data type, REAL.'' || a.SetAt(0, 3) OR: a[0] = 3
|-
||'''GetAt'''(''index'') || This retrieves the value (type real) of the element from the array, which corresponds to the given ''index''. || Real || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. || e = a.GetAt(0) or: e = a[0]
|-
||'''IncAt'''(''Index, value'') || This increases the element of the array by the specified value. || || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. ''value :'' the value to which the specified element, in the array, will be increased. This is of data type REAL.'' || "a.IncAt(3, 10)" is equivalent to: temp = a.GetAt(3) a.SetAt(3, temp + 10)
|-
||'''DecAt'''(''Index, value'') || This decreases the element of the array by the specified value. || || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. ''value :'' the value to which the specified element, in the array, will be decreased. This is of data type REAL.'' || "a.DecAt(3, 5)" is equivalent to: temp = a.GetAt(3) a.SetAt(3, temp - 5)"
|-
||'''Sum'''() || This calculates the sum of all elements in the array. || Real || None || e = a.Sum()
|-
||'''Avg'''() || This calculates the average of all elements in the array. || Real || None || e = a.Avg()
|-
||'''Min'''() || This returns the minimum value of all elements in the array. || Real || None || e = a.Min()
|-
||'''MinIndex'''() || This returns the index of the minimum value in the array. If multiple entries of equal minimum value, the first index is returned. Return value is -1 for empty array. || integer || None || d = a.MinIndex()
|-
||'''Max'''() || This returns the maximum value of all elements in the array. || Real || None || e = a.Max()
|-
||'''MaxIndex'''() || This returns the index of the maximum value in the array. If multiple entries of equal maximum value, the first index is returned. Return value is -1 for empty array. || integer || None || d = a.MaxIndex()
|-
|'''Norm'''() {{Available139|30807}} || This normalises the contents of the array such that the sum is 1. Equivalent to a.OpDiv(a.Sum()). || || None || a.Norm()
|-
|'''Reverse'''() {{Available139|30807}} || This reverses the sequence of all elements in the array. || || None || a.Reverse()
|-
|'''Sort'''(''Ascending/Descending'') || This re-arranges all elements in the array in ascending / descending order. || || 0: Descending order, 1: Ascending order || a.Sort(1)
|-
|'''IsSorted'''(''Ascending/Descending'') || This checks if the array is sorted in ascending / descending order. Returns True if array is sorted in the specified order. || Bit || 0: Descending order, 1: Ascending order || SortOK = a.IsSorted(1)
|-
||
'''Load'''(''arrayfilename'')
||
This creates a new array from a file.
* The first element on each line, of the specified file, is read in as an element of the array, until either an empty line or end-of-file character is reached.
* The function returns the value, True if the file was read or, False if the file was not read.
'''Note:''' if any elements exist in the array, prior to calling '''Load''', these elements will be overridden.''
||
Bit
||
''arrayfileName :'' either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder.
||
ArrayFileName = "c:\SysCAD\array.csv" 
OK = b.Load(ArrayFileName) 
or 
OK = c.Load("$Prj\data.txt")
|-
||
'''Save'''(''arrayfilename'')
||
This saves the array data to a comma separated text file.
* If the specified file exists it is overwritten.
* The function returns, True if the file was saved or, False if the file was not saved.
* This could fail for any file access reason, for example: invalid folder, invalid filename, file access error, file already open in another application, etc.
||
Bit
||
''arrayfileName :'' either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder.
||
OK = a.Save("$Prj\data_output.txt")

|-
||
'''CopyToClipboard'''()
||
This saves the array data to the clipboard.
The function returns the value, True.
||
Bit
||
None
||
OK = a.CopyToClipboard()
|-
||'''SetAll'''(''value'') || This sets all the elements of the array to the specified ''value''. || || ''value :'' the required initialising value. This is of data type REAL.'' || a.SetAll(0)
|-
|'''Scale'''(''value'') || All the elements of the array are scaled by the specified ''value'' (New value = original value * Scale). || || ''value :'' the required scaling factor. This is of data type REAL.'' || a.Scale(2) - Each value of the Array "a" will be increased by factor of 2.
|-
|'''Offset'''(''value'') || All the elements of the array are offset by the specified ''value'' (New value = original value + Offset). || || ''value :'' the required offset value. This is of data type REAL.'' || a.Offset(5) - Each value of the Array "a" will be increased by 5.
|-
|'''Copy'''(''Array'') || All the elements of the specified array are copied into the new array. || || ''Array:'' the name of the array to copy from. This is an ARRAY class.'' || PreVals.Copy(a) - The values in Array "a" are copied into the Array "PreVals".
|-
|'''Append'''(''Array'') {{Available139|30807}} || All the elements of the specified array are added to the end of the existing array. The new length of the array will be the sum of the original length plus the length of the specified array.|| || ''Array:'' the name of the array to append. This is an ARRAY class.'' || PreVals.Append(a) - The values in Array "a" are appended to the end of the Array "PreVals".
|-
|'''AppendItem'''(''value'') {{Available139|30874}} || Increase the length of the array by one with the supplied value. || || ''value:'' the value to which the last element in the array will be set. || a.AppendItem(42)
|-
|'''InsertAt'''(''index'', ''value'') {{Available139|32112}} || Increase the length of the array by one inserting the supplied value at the specified ''index''. || || ''index:'' the zero based index in array where the value must be inserted. Index data type is INTEGER and must be in range for Array length. ''value:'' the value to be set at the new inserted element in the array. || a.InsertAt(0, 42) - Inserts 42 at start of array.
|-
|'''RemoveAt'''(''index'', ''count'') {{Available139|32112}} || Decrease the length of the array by removing ''count'' (or less) values starting at the specified ''index''. || || ''index:'' the zero based index in array where values must be deleted. Index data type is INTEGER and must be in range for Array length. ''count:'' the number of elements to be removed. The value of ''count'' may be large, exceeding the current array length in which case all elements from the specified ''index'' are removed. Count data type is INTEGER. || a.RemoveAt(5, 1) - Removes one element at index 5.
|-
|'''IsEqual'''(''Array'') || This compares the current array with the specified array data, if each element of the array are equal, the function returns the value, True. || Bit || ''Array:'' the name of the array to compare with. This is an ARRAY class.'' || EqualOK = PreVals.IsEqual(a) - The values in array "PreVals" are compared to the values of the Array "a". Returns true if they are equal.
|-
|'''Add'''(''Array'') || This function performs addition between current array and a specified array. New value for each element in current array = value in current array + specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || AddOK = NewA.add(A1) (each element in NewA = NewA + A1)
|-
|'''Sub'''(''Array'') || This function performs subtraction between current array and a specified array. New value for each element in current array = value in current array - specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit ||''Array:'' the name of the specified array. This is an ARRAY class. || SubOK = NewA.Sub(A1) (each element in NewA = NewA - A1)
|-
|'''Mult'''(''Array'') || This function performs multiplication between current array and a specified array. New value for each element in current array = value in current array x specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || MultOK = NewA.Mult(A1) (each element in NewA = NewA * A1)
|-
|'''Div'''(''Array'') || This function performs division between current array and a specified array. New value for each element in current array = value in current array / specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit ||''Array:'' the name of the specified array. This is an ARRAY class. || DivOK = NewA.Div(A1) (each element in NewA = NewA / A1)
|-
|'''CopyAdd'''(''Array1, Array2'') || This function performs addition between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 + array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.''|| AddOK = NewA.CopyAdd(A1, A2) (each element in NewA = A1 + A2)
|-
|'''CopySub'''(''Array1, Array2'') || This function performs subtraction between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 - array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.|| AddOK = NewA.CopySub(A1, A2) (each element in NewA = A1 - A2)
|-
|'''CopyMult'''(''Array1, Array2'') || This function performs multiplication between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 x array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class. || AddOK = NewA.CopyMult(A1, A2) (each element in NewA = A1 * A2)
|-
|'''CopyDiv'''(''Array1, Array2'') || This function performs division between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 / array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.|| AddOK = NewA.CopyDiv(A1, A2) (each element in NewA = A1 / A2)
|-
|'''Inner'''(''Array'') || This returns the Sum of Element i (Current Array * Specified Array). The two arrays must have the same length, otherwise error is returned. || REAL || ''Array:'' the name of the second array. This is an ARRAY class.'' || DotProduct = a.Inner(PreVals)
|-
|'''CircConv'''(''Array'') {{Available139|30613}} || This function performs circular convolution calculation between the current array and a specified array. New value for each element in current array is calculated as the integral of the product of the two arrays after one is reversed and shifted. The values in the current array will be replaced with the new value. The two arrays are expected to have the same length. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || AddOK = NewA.CirConv(A1) (each element in NewA = circular convolution of NewA and A1)
|-
|'''CopyCircConv'''(''Array1, Array2'') {{Available139|30613}} || This function performs circular convolution calculation between two arrays and stores the values in a new array (current array). Value for each element in current array is calculated as the integral of the product of the two arrays after one is reversed and shifted. The two arrays are expected to have the same length. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.''|| AddOK = NewA.CopyCirConv(A1, A2) (each element in NewA = circular convolution of A1 and A2)
|-
|'''SetFromStr'''(''Str s, Str Separ'') {{Available139|35544}}|| This function enables the unpacking of a string into an array, converting each element into a number. It internally utilises the StrToFlt function. The array’s length is determined by the number of items derived from unpacking the string.|| REAL || ''s'' is the string that requires unpacking. ''Separ'' is the separator used within the string ‘s’ to define the divisions. ||x.SetFromStr("35,4,30", ",") will unpack the three numbers into the array ‘x’, resulting in x[0]=35, x[1]=4, and x[2]=30.
|-
|'''CopyToStr'''(''Str Separ'') {{Available139|35544}}|| This function enables the consolidation of a ‘Array’ into a single string. || STRING|| ''Separ'' denotes the delimiter used within the string ‘s’ to demarcate its segments. ||x.CopyToStr(",") will combine the elements of the 'Array' named 'x' into the string "35,4,30".
|-
|'''PushBack'''(''value'') '''PushFront'''(''value'') {{Available140}}|| These methods put ''value'' at the start or end of the array and increase the size. || || ''value'': the value to be set. || Equivalent to InsertAt(0, value)
|-
|'''PopBack'''() '''PopFront'''() {{Available140}}|| These functions return the value at the start or end, and decrease the size. || Real || || If A = [1., 2., 3.], then A.PopBack() returns 3.0 and A = [1, 2]
|-
|'''PushFrontPopBack'''(''value'') '''PushBackPopFront'''(''value'') {{Available140}}|| These functions treat the array as a FIFO queue, adding an item at one end and removing and returning the item at the other end. All items are moved up or down in the array and the size is unchanged || Real || Real ||
|}

=== Watch ===

The '''Watch''' keyword can be used to display the Array values in the Access Window.

'''Syntax''':
* Individual elements in the array can be made visible - e.g. "Watch A[2]" or "Watch A@[2]".
* A range of array elements can be made visible - e.g. "Watch A[All,5]" which would show the first 5 elements of the array.
* If the "@" symbol is included, then the array elements will be read only fields in the access window.

=== Array with Constant Values ===

The user may declare an array with a set of constant values. This allows the user to set up an array with known values for direct use. It can be a useful alternative to reading values from a CSV file. Once defined, the contents or size of this constant Array cannot be changed. Where a number is not specified for an entry, 0 is assumed. The contents of the array are not saved as they are defined in the code. From {{Available139|32217||y}}, the list can include system constants (for example NAN or PI), or user defined constants. From {{Available139|32325||y}}, the const keyword should be used, otherwise a load warning (or error) is given.

The syntax is:
<syntaxhighlight lang="pgm">
const ARRAY a = {n1,n2,n3,....} ;Syntax from {{Available139|32325||y}}
ARRAY a = {n1,n2,n3,....} ;Syntax before {{Available139|32325||y}}
;where n1, n2 etc. are real numbers or constants.
;Example
const Array SomePrimes = {2,3,5,7,11,13,17,19,23,29,31,37,41,43,47,53,59,61,67,71}
</syntaxhighlight>

=== Caution ===

Using a GetAt within a SetAt can sometimes fail. This may be for expressions with multiple array references.
<syntaxhighlight lang="pgm">
;For example:
a.SetAt(i, a.GetAt(i+1)) ;This can sometimes fail

;The solution is to use a temporary variable to first retrieve the GetAt value and then call SetAt as follows:
Real Tmp
Tmp = a.GetAt(i+1)
a.SetAt(i, Tmp)
</syntaxhighlight>

== Example ==

<syntaxhighlight lang="pgm">
STRING ArrayFileName
REAL d, e, f, Total@, Average@, Minimum@, Maximum@, DotProduct@
BIT OK@, CopyOK@, SortOK@, AddOK@, SubOK@
ARRAY a ;declares array instance.
ARRAY b{e}, c{e} ;declares array instances that are excluded from save (for efficiency).
const ARRAY x = {60,35,25,62,105} ;declares an array z with constant values.
;ARRAY x = {60,35,25,62,105} ;Old syntax before {{Removed139|32325||y}}
ARRAY y, y1, y2
const ARRAY y3 = {20,35,45,62,105,150} ;declares an array y3 with constant values.
const ARRAY z = {20,35,45,62,105} ;declares an array z with constant values.

Sub InitialiseSolution()
ArrayFileName = "c:\SysCAD\array.csv"
OK = b.Load(ArrayFileName)
OK = c.Load("$Prj\data.txt")
a.SetLen(5) ;sets the array length
y.copy(x) ;array x is copied into array y, returns {60,35,25,62,105}
CopyOK = y.isEqual(x) ;compares array y with array x, returns true
y.sort(1) ;sorts array y in ascending order, returns {25,35,60,62,105}
SortOK = y.IsSorted(1) ;checks if array y is sorted in ascending order, returns true
y1.copy(y) ;copies y, returns {25,35,60,62,105}
y1.scale(2) ;multiplies each element by scaling factor of 2, returns {50, 70, 120, 124, 210}
y2.copy(y) ;copies y, returns {25,35,60,62,105}
y2.offset(5) ;adds each element by offset factor of 5, returns {30, 40, 65, 67, 110}
AddOK = y.add(y2) ;Adds each element of y to elements of y2, y now becomes {55, 75, 125, 129, 215}, returns true
SubOK = y1.sub(y3) ;returns false since array length of y1 does not equal to y3. Array y1 unchanged.
DotProduct = y.inner(y2) ;sum of each element y_i * y2_i, returns 45068
EndSub

;Logic
d = a.GetLen() ;gets the array length
a.SetAll(2.2/2) ;sets all elements
a.IncAt(0, 7.0) ;increments the first element
a[d-1] = 3.3 ;sets last element
e = a[0] ;gets first element
f = z[3] ;gets the fourth element of array z, so f = 62
Total = z.Sum() ;gets the sum of all the values in array z, Total = 267
Average = z.Avg() ;gets the average of all the values in array z, Average = 53.4
Minimum = z.Min() ;gets the minimum of all the values in array z, Minimum = 20
Maximum = z.Max() ;gets the maximum of all the values in array z, Maximum = 105
$
</syntaxhighlight>

See also: [[Python Example - Optimization#Calculating_the_objective_error | Optimisation Example]] shows using these Array tools in a real example for plant tuning calculating an objective function.

Array Class

2026-05-26T15:30:09Z

Rod.Stephenson: /* Member Functions */

[[Category:PGM]] [[Category:Examples]]
{{Navigation|[[PGMs]]|[[Class - Introduction|Classes]]}}
{{User Defined Classes Header Table |currentpage=4}}

----
{{TOC}}
== Description ==

The ARRAY class provides member functions to create a dynamic array and manipulate its elements.
* The user may read in an array from a file. The file may be either a CSV file, created using Excel, or a TXT file, created using a test editor such as Notepad++.
* The user may set constant values into an array when it is declared.

'''Notes:'''
# The initial length of the array is zero.
# '''The array is zero indexed''', i.e. the index of the first element in the array is zero, and NOT 1. Therefore, the final element in an array of length ''n'' will have an index = ''n-1''.
# If the index is out of range (0 <= ''index'' < ''length'') then a runtime "PGM class execution error" will occur and the ARRAY operation will be ignored.
# The Array class allows user to Get / Set ''numeric values'' only. Please see [[StrArray Class]] for getting/setting ''String values''.

== Data Members ==

None

== Member Functions ==
The examples in the table below is based on the following variables and array declarations.

<syntaxhighlight lang="pgm">
STRING ArrayFileName
REAL e, DotProduct
LONG d
BIT OK@, EqualOK@, SortOK@, AddOK@, SubOK@, MultOK@, DivOK@
ARRAY a, b, c, NewA, A1, A2, PreVals, z ;declares array instances
</syntaxhighlight>

{| border="1" cellpadding="5" cellspacing="0"
| width="15%" |'''Call ''' || width="35%" | '''Functionality'''|| width="6%" |'''Return Type ''' || width="25%" |'''Parameters ''' || width="30%" | '''Example'''
|-
||'''SetLen'''(''length'') || Sets the size of the array to ''length'' || || ''length :'' the required length of the array, is of data type INTEGER || a.SetLen(5)
|-
||'''GetLen'''() || The function returns the length of the array. || integer || None || d = a.GetLen()
|-
||'''SetSize'''(''length'') {{Available139|30807}} || Sets the size of the array to ''length''. SetSize() function is an equivalent alternative to SetLen() || || ''length :'' the required size of the array, is of data type INTEGER || a.SetSize(5)
|-
||'''Size'''() {{Available139|30807}} || The function returns the length of the array. Size() function is an equivalent alternative to GetLen(). || integer || None || d = a.Size()
|-
|| '''SetAt'''(''index, value'') || This sets the element of the array, which corresponds to the given ''index'' to the specified ''value''. || || ''index'': the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type, INTEGER. ''value :'' the value to which the specified element, in the array, will be set. This is of data type, REAL.'' || a.SetAt(0, 3) OR: a[0] = 3
|-
||'''GetAt'''(''index'') || This retrieves the value (type real) of the element from the array, which corresponds to the given ''index''. || Real || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. || e = a.GetAt(0) or: e = a[0]
|-
||'''IncAt'''(''Index, value'') || This increases the element of the array by the specified value. || || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. ''value :'' the value to which the specified element, in the array, will be increased. This is of data type REAL.'' || "a.IncAt(3, 10)" is equivalent to: temp = a.GetAt(3) a.SetAt(3, temp + 10)
|-
||'''DecAt'''(''Index, value'') || This decreases the element of the array by the specified value. || || ''index :'' the index of the required entry in the array ('''Note:''' index starts at zero). This is of data type INTEGER. ''value :'' the value to which the specified element, in the array, will be decreased. This is of data type REAL.'' || "a.DecAt(3, 5)" is equivalent to: temp = a.GetAt(3) a.SetAt(3, temp - 5)"
|-
||'''Sum'''() || This calculates the sum of all elements in the array. || Real || None || e = a.Sum()
|-
||'''Avg'''() || This calculates the average of all elements in the array. || Real || None || e = a.Avg()
|-
||'''Min'''() || This returns the minimum value of all elements in the array. || Real || None || e = a.Min()
|-
||'''MinIndex'''() || This returns the index of the minimum value in the array. If multiple entries of equal minimum value, the first index is returned. Return value is -1 for empty array. || integer || None || d = a.MinIndex()
|-
||'''Max'''() || This returns the maximum value of all elements in the array. || Real || None || e = a.Max()
|-
||'''MaxIndex'''() || This returns the index of the maximum value in the array. If multiple entries of equal maximum value, the first index is returned. Return value is -1 for empty array. || integer || None || d = a.MaxIndex()
|-
|'''Norm'''() {{Available139|30807}} || This normalises the contents of the array such that the sum is 1. Equivalent to a.OpDiv(a.Sum()). || || None || a.Norm()
|-
|'''Reverse'''() {{Available139|30807}} || This reverses the sequence of all elements in the array. || || None || a.Reverse()
|-
|'''Sort'''(''Ascending/Descending'') || This re-arranges all elements in the array in ascending / descending order. || || 0: Descending order, 1: Ascending order || a.Sort(1)
|-
|'''IsSorted'''(''Ascending/Descending'') || This checks if the array is sorted in ascending / descending order. Returns True if array is sorted in the specified order. || Bit || 0: Descending order, 1: Ascending order || SortOK = a.IsSorted(1)
|-
||
'''Load'''(''arrayfilename'')
||
This creates a new array from a file.
* The first element on each line, of the specified file, is read in as an element of the array, until either an empty line or end-of-file character is reached.
* The function returns the value, True if the file was read or, False if the file was not read.
'''Note:''' if any elements exist in the array, prior to calling '''Load''', these elements will be overridden.''
||
Bit
||
''arrayfileName :'' either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder.
||
ArrayFileName = "c:\SysCAD\array.csv" 
OK = b.Load(ArrayFileName) 
or 
OK = c.Load("$Prj\data.txt")
|-
||
'''Save'''(''arrayfilename'')
||
This saves the array data to a comma separated text file.
* If the specified file exists it is overwritten.
* The function returns, True if the file was saved or, False if the file was not saved.
* This could fail for any file access reason, for example: invalid folder, invalid filename, file access error, file already open in another application, etc.
||
Bit
||
''arrayfileName :'' either the actual filename and path in quotations or a STR variable, which refers to the file. Use $Prj in the folder string for folders relative to the project folder.
||
OK = a.Save("$Prj\data_output.txt")

|-
||
'''CopyToClipboard'''()
||
This saves the array data to the clipboard.
The function returns the value, True.
||
Bit
||
None
||
OK = a.CopyToClipboard()
|-
||'''SetAll'''(''value'') || This sets all the elements of the array to the specified ''value''. || || ''value :'' the required initialising value. This is of data type REAL.'' || a.SetAll(0)
|-
|'''Scale'''(''value'') || All the elements of the array are scaled by the specified ''value'' (New value = original value * Scale). || || ''value :'' the required scaling factor. This is of data type REAL.'' || a.Scale(2) - Each value of the Array "a" will be increased by factor of 2.
|-
|'''Offset'''(''value'') || All the elements of the array are offset by the specified ''value'' (New value = original value + Offset). || || ''value :'' the required offset value. This is of data type REAL.'' || a.Offset(5) - Each value of the Array "a" will be increased by 5.
|-
|'''Copy'''(''Array'') || All the elements of the specified array are copied into the new array. || || ''Array:'' the name of the array to copy from. This is an ARRAY class.'' || PreVals.Copy(a) - The values in Array "a" are copied into the Array "PreVals".
|-
|'''Append'''(''Array'') {{Available139|30807}} || All the elements of the specified array are added to the end of the existing array. The new length of the array will be the sum of the original length plus the length of the specified array.|| || ''Array:'' the name of the array to append. This is an ARRAY class.'' || PreVals.Append(a) - The values in Array "a" are appended to the end of the Array "PreVals".
|-
|'''AppendItem'''(''value'') {{Available139|30874}} || Increase the length of the array by one with the supplied value. || || ''value:'' the value to which the last element in the array will be set. || a.AppendItem(42)
|-
|'''InsertAt'''(''index'', ''value'') {{Available139|32112}} || Increase the length of the array by one inserting the supplied value at the specified ''index''. || || ''index:'' the zero based index in array where the value must be inserted. Index data type is INTEGER and must be in range for Array length. ''value:'' the value to be set at the new inserted element in the array. || a.InsertAt(0, 42) - Inserts 42 at start of array.
|-
|'''RemoveAt'''(''index'', ''count'') {{Available139|32112}} || Decrease the length of the array by removing ''count'' (or less) values starting at the specified ''index''. || || ''index:'' the zero based index in array where values must be deleted. Index data type is INTEGER and must be in range for Array length. ''count:'' the number of elements to be removed. The value of ''count'' may be large, exceeding the current array length in which case all elements from the specified ''index'' are removed. Count data type is INTEGER. || a.RemoveAt(5, 1) - Removes one element at index 5.
|-
|'''IsEqual'''(''Array'') || This compares the current array with the specified array data, if each element of the array are equal, the function returns the value, True. || Bit || ''Array:'' the name of the array to compare with. This is an ARRAY class.'' || EqualOK = PreVals.IsEqual(a) - The values in array "PreVals" are compared to the values of the Array "a". Returns true if they are equal.
|-
|'''Add'''(''Array'') || This function performs addition between current array and a specified array. New value for each element in current array = value in current array + specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || AddOK = NewA.add(A1) (each element in NewA = NewA + A1)
|-
|'''Sub'''(''Array'') || This function performs subtraction between current array and a specified array. New value for each element in current array = value in current array - specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit ||''Array:'' the name of the specified array. This is an ARRAY class. || SubOK = NewA.Sub(A1) (each element in NewA = NewA - A1)
|-
|'''Mult'''(''Array'') || This function performs multiplication between current array and a specified array. New value for each element in current array = value in current array x specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || MultOK = NewA.Mult(A1) (each element in NewA = NewA * A1)
|-
|'''Div'''(''Array'') || This function performs division between current array and a specified array. New value for each element in current array = value in current array / specified array. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit ||''Array:'' the name of the specified array. This is an ARRAY class. || DivOK = NewA.Div(A1) (each element in NewA = NewA / A1)
|-
|'''CopyAdd'''(''Array1, Array2'') || This function performs addition between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 + array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.''|| AddOK = NewA.CopyAdd(A1, A2) (each element in NewA = A1 + A2)
|-
|'''CopySub'''(''Array1, Array2'') || This function performs subtraction between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 - array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.|| AddOK = NewA.CopySub(A1, A2) (each element in NewA = A1 - A2)
|-
|'''CopyMult'''(''Array1, Array2'') || This function performs multiplication between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 x array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class. || AddOK = NewA.CopyMult(A1, A2) (each element in NewA = A1 * A2)
|-
|'''CopyDiv'''(''Array1, Array2'') || This function performs division between two arrays and stores the values in a new array (current array). Value for each element in current array = value in array1 / array2. The two arrays must have the same length, otherwise value remains unchanged and error is returned. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.|| AddOK = NewA.CopyDiv(A1, A2) (each element in NewA = A1 / A2)
|-
|'''Inner'''(''Array'') || This returns the Sum of Element i (Current Array * Specified Array). The two arrays must have the same length, otherwise error is returned. || REAL || ''Array:'' the name of the second array. This is an ARRAY class.'' || DotProduct = a.Inner(PreVals)
|-
|'''CircConv'''(''Array'') {{Available139|30613}} || This function performs circular convolution calculation between the current array and a specified array. New value for each element in current array is calculated as the integral of the product of the two arrays after one is reversed and shifted. The values in the current array will be replaced with the new value. The two arrays are expected to have the same length. || Bit || ''Array:'' the name of the specified array. This is an ARRAY class. || AddOK = NewA.CirConv(A1) (each element in NewA = circular convolution of NewA and A1)
|-
|'''CopyCircConv'''(''Array1, Array2'') {{Available139|30613}} || This function performs circular convolution calculation between two arrays and stores the values in a new array (current array). Value for each element in current array is calculated as the integral of the product of the two arrays after one is reversed and shifted. The two arrays are expected to have the same length. || Bit || ''Array1:'' the name of the first specified array. This is an ARRAY class. ''Array2:'' the name of the second specified array. This is an ARRAY class.''|| AddOK = NewA.CopyCirConv(A1, A2) (each element in NewA = circular convolution of A1 and A2)
|-
|'''SetFromStr'''(''Str s, Str Separ'') {{Available139|35544}}|| This function enables the unpacking of a string into an array, converting each element into a number. It internally utilises the StrToFlt function. The array’s length is determined by the number of items derived from unpacking the string.|| REAL || ''s'' is the string that requires unpacking. ''Separ'' is the separator used within the string ‘s’ to define the divisions. ||x.SetFromStr("35,4,30", ",") will unpack the three numbers into the array ‘x’, resulting in x[0]=35, x[1]=4, and x[2]=30.
|-
|'''CopyToStr'''(''Str Separ'') {{Available139|35544}}|| This function enables the consolidation of a ‘Array’ into a single string. || STRING|| ''Separ'' denotes the delimiter used within the string ‘s’ to demarcate its segments. ||x.CopyToStr(",") will combine the elements of the 'Array' named 'x' into the string "35,4,30".
|-
|'''PushBack'''(''value'') '''PushFront'''(''value'') {{Available140}}|| These methods put ''value'' at the start or end of the array and increase the size. || || ''value'': the value to be set. || Equivalent to InsertAt(0, value)
|-
|'''PopBack'''() '''PopFront'''() {{Available140}}|| These functions return the value at the start or end, and decrease the size. || Real || ||
|-
|'''PushFrontPopBack'''(''value'') '''PushBackPopFront'''(''value'') {{Available140}}|| These functions treat the array as a FIFO queue, adding an item at one end and removing and returning the item at the other end. || Real || Real ||
|}

=== Watch ===

The '''Watch''' keyword can be used to display the Array values in the Access Window.

'''Syntax''':
* Individual elements in the array can be made visible - e.g. "Watch A[2]" or "Watch A@[2]".
* A range of array elements can be made visible - e.g. "Watch A[All,5]" which would show the first 5 elements of the array.
* If the "@" symbol is included, then the array elements will be read only fields in the access window.

=== Array with Constant Values ===

The user may declare an array with a set of constant values. This allows the user to set up an array with known values for direct use. It can be a useful alternative to reading values from a CSV file. Once defined, the contents or size of this constant Array cannot be changed. Where a number is not specified for an entry, 0 is assumed. The contents of the array are not saved as they are defined in the code. From {{Available139|32217||y}}, the list can include system constants (for example NAN or PI), or user defined constants. From {{Available139|32325||y}}, the const keyword should be used, otherwise a load warning (or error) is given.

The syntax is:
<syntaxhighlight lang="pgm">
const ARRAY a = {n1,n2,n3,....} ;Syntax from {{Available139|32325||y}}
ARRAY a = {n1,n2,n3,....} ;Syntax before {{Available139|32325||y}}
;where n1, n2 etc. are real numbers or constants.
;Example
const Array SomePrimes = {2,3,5,7,11,13,17,19,23,29,31,37,41,43,47,53,59,61,67,71}
</syntaxhighlight>

=== Caution ===

Using a GetAt within a SetAt can sometimes fail. This may be for expressions with multiple array references.
<syntaxhighlight lang="pgm">
;For example:
a.SetAt(i, a.GetAt(i+1)) ;This can sometimes fail

;The solution is to use a temporary variable to first retrieve the GetAt value and then call SetAt as follows:
Real Tmp
Tmp = a.GetAt(i+1)
a.SetAt(i, Tmp)
</syntaxhighlight>

== Example ==

<syntaxhighlight lang="pgm">
STRING ArrayFileName
REAL d, e, f, Total@, Average@, Minimum@, Maximum@, DotProduct@
BIT OK@, CopyOK@, SortOK@, AddOK@, SubOK@
ARRAY a ;declares array instance.
ARRAY b{e}, c{e} ;declares array instances that are excluded from save (for efficiency).
const ARRAY x = {60,35,25,62,105} ;declares an array z with constant values.
;ARRAY x = {60,35,25,62,105} ;Old syntax before {{Removed139|32325||y}}
ARRAY y, y1, y2
const ARRAY y3 = {20,35,45,62,105,150} ;declares an array y3 with constant values.
const ARRAY z = {20,35,45,62,105} ;declares an array z with constant values.

Sub InitialiseSolution()
ArrayFileName = "c:\SysCAD\array.csv"
OK = b.Load(ArrayFileName)
OK = c.Load("$Prj\data.txt")
a.SetLen(5) ;sets the array length
y.copy(x) ;array x is copied into array y, returns {60,35,25,62,105}
CopyOK = y.isEqual(x) ;compares array y with array x, returns true
y.sort(1) ;sorts array y in ascending order, returns {25,35,60,62,105}
SortOK = y.IsSorted(1) ;checks if array y is sorted in ascending order, returns true
y1.copy(y) ;copies y, returns {25,35,60,62,105}
y1.scale(2) ;multiplies each element by scaling factor of 2, returns {50, 70, 120, 124, 210}
y2.copy(y) ;copies y, returns {25,35,60,62,105}
y2.offset(5) ;adds each element by offset factor of 5, returns {30, 40, 65, 67, 110}
AddOK = y.add(y2) ;Adds each element of y to elements of y2, y now becomes {55, 75, 125, 129, 215}, returns true
SubOK = y1.sub(y3) ;returns false since array length of y1 does not equal to y3. Array y1 unchanged.
DotProduct = y.inner(y2) ;sum of each element y_i * y2_i, returns 45068
EndSub

;Logic
d = a.GetLen() ;gets the array length
a.SetAll(2.2/2) ;sets all elements
a.IncAt(0, 7.0) ;increments the first element
a[d-1] = 3.3 ;sets last element
e = a[0] ;gets first element
f = z[3] ;gets the fourth element of array z, so f = 62
Total = z.Sum() ;gets the sum of all the values in array z, Total = 267
Average = z.Avg() ;gets the average of all the values in array z, Average = 53.4
Minimum = z.Min() ;gets the minimum of all the values in array z, Minimum = 20
Maximum = z.Max() ;gets the maximum of all the values in array z, Maximum = 105
$
</syntaxhighlight>

See also: [[Python Example - Optimization#Calculating_the_objective_error | Optimisation Example]] shows using these Array tools in a real example for plant tuning calculating an objective function.

Archive Reporter

2026-05-12T09:03:04Z

Rod.Stephenson: /* Reporting Options */

[[Category:Reports]]
{{Navigation|[[User Guide]]|[[Reports]]}}
{|border="1" cellpadding="5" cellspacing="0"
|-
!Width=300 font style="background: #ebebeb"|[[Archive Reporter]]
!Width=300 |[[Archive Editor]]
!Width=300 |[[Archive (sac) File Text Format]]
|}

'''Related Links:''' [[Planning Example Project]], [[Tailings Dam Example Project]], [[Waste Handling with Batch Digestion Example Project]]
----
{{TOC|x=20%}}
== Introduction ==

The '''Archive Reporter''' is used with Dynamic projects to report data directly to a database, CSV or text file while a project is running. This has some similarities with the SysCAD [[Historian]], however the archiver has significantly greater functionality so the use of the historian for reporting is not recommended.

The user specifies how many tables of data are required (maximum is 500), the frequency of reporting (each table may be reported at a user specified time) and the tags that are reported in each table. These settings are recorded in a text file by the Archive Editor. The maximum number of Fields (including [[#Time_Fields|Time Fields]]) in a Table is 2000 (for DB-SQLITE .db3 format) and 3000 (for csv format).

Please also note that this file is loaded (or reloaded) from the [[Project Settings]] Archive tab page, as shown in the sections below.

== Archive Configuration ==

To use the Archiver:
# Go to ''Edit - Project Settings''
# The dialog box shown below will be displayed
# Go to the ''Archive'' page and tick the 'On' box
# The SysCAD Archive Configuration (.sac) file will be created
# Click on the 'Edit' button to edit the Archive.sac file

[[Image:Project Settings-Archive.jpg]]

The Settings are explained in the table below:

{| border="1" cellpadding="5" cellspacing="0"
|'''Setting / Tick Box''' || '''Description'''
|-
| colspan="2" font style="background: #ebebeb" |
=== Archive Reporter Configuration ===
|-
| On || The user must tick this box to enable the Archive Reporter.
|-
|| Name || This will be the name of the Archive Reporter file. The default name is Archive.sac and it is automatically created in the project folder when the user ticks the 'On' box. Users can choose to have a different file name but only one sac file can be used per project.
|-
| Browse || The user may browse for an alternative Archive file using this button.
|}

Press the '''Edit''' button to launch the Archive Editor.

Pressing the '''Reload''' button loads the Archive.sac file into SysCAD, which will check the file and display messages in the Messages window.

== System Settings ==

The Settings are explained in the table below:

{| border="1" cellpadding="5" cellspacing="0"
|'''Setting / Tick Box''' || '''Description'''
|-
| colspan="2" font style="background: #ebebeb" |
=== Time Fields ===
|-
| Date and Time || Every table will contain a column with the simulation time and date for the reported values. The format for this column will be Date:Time
|-
| Date Only || Every table will contain a column with the simulation date for the reported values.
|-
| Time Only || Every table will contain a column with the simulation time for the reported values.
|-
| Elapsed as HMS || Every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be hh:mm:ss
|-
| Elapsed Time || Unless the user selects 'Off', every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be a single value, and will display the total elapsed time as seconds, minutes, hours or days, depending on the user selection.
|-
| colspan="2" font style="background: #ebebeb" |

=== System Tables ===
|-
| Message Log || If the user ticks this box, all simulation messages will be written to a log file in the Archive folder.
|-
| Event Log || If the user ticks this box, all Events will be written to a log file in the Archive folder.
|-
| colspan="2" font style="background: #ebebeb" | ''Standard Fields'' These tick boxes determine what information is written to the Message Log file.
|-
| Source || The source of the message will be logged.
|-
| Tag || The unit tag that is source of the message will be logged.
|-
| Command || All SysCAD commands will be logged, e.g. 'Stop', 'Run', etc.
|-
| Type || The type of message will be logged, i.e. Error, Warning, etc.
|-
| Message || Messages will be displayed. If this is not ticked, then only Errors and Warnings will be logged.
|-
| ID No || The ID of the message will be logged.
|-
| Iteration || The Iteration of the message will be logged.
|-
| Call No || The Call number for the message will be logged.
|-
| Sequence No || The Sequence number of the message will be logged.
|}

== Reporting Options ==

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Option''' || '''Description'''
|-
|colspan=2| On || If On = 1, the table will be created. If On = 0, the table will not be created.
|-
|colspan=2| Name || The name of the table (for DB formats) or name of the file for csv/txt file formats.
|-
| rowspan="3" valign="top" | Format || DB-SQLITE || Data will be saved in Archive.db3 SQ Lite database in the project folder (Maximum fields per table is 2000)
|-
|| CSV || Data will be saved in a CSV file (Maximum fields per table is 3000)
|-
|| TXT || Data will be saved in a Text (txt) file
|-
| rowspan="2" valign="top" | Clear || Rewind || Clear archive file on next run.
|-
|| False || Add to existing archive file on next run. This can be overridden by other settings on the [[Solver Setting - Scenario]] page such as the RestartArchive option.
|}

'''Note:''' Each table can only have one format but within the same archive file, different tables can have different formats 

=== CSV and TXT File Options ===

If the Format chosen is CSV or TXT, then the following options are relevant.

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Description'''
|-
|Path || The path and folder name for storing CSV & TXT files (usually with the Project)
|-
|SigDigits || The number of significant digits for the tags that are reported to CSV & TXT files. Recommendation is 16. Accepted range is 2-17.
|}

=== Period and Offset ===

The Period and Offset for reporting can be specified. This is not required if the user specifies a Trigger, but note that both Periods and Triggers can be used for the same table.

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Description'''
|-
|| Period || Time frequency for reporting fields, where time zero is at start. '''Note 1:''' The period is relative to midnight, not the simulation start time. '''Note 2:''' If the period is not divisible by 24 hours, the reporting will not be at the same time each day.
|-
|| Offset || Time offset within the specified period. This affects when the first set of data is recorded. '''Note:''' The offset is relative to midnight, not the simulation start time.
|}

'''Notes:'''
* Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
* If one or more Triggers are used, a period & offset is not relevant or required.
* If no triggers or period are specified then the table will not accumulate data.
* Note that period and offset are relative to midnight. If your start time is not on a reporting period relative to midnight AND you want to report relative to the start time, then you need to specify an offset to achieve this. For example, if you want to report every 24 hours and the start time is 8:00am, then the offset should be 8 hours.

== Trigger Options ==

The user may specify one or more Triggers that will cause the values in the table to be reported. There can be any number of triggers. If the conditions of any of the triggers are met, then the fields will be reported.

The triggers are numbered and include three terms as described below, a description, a SysCAD tag and the Trigger Test.

{| border="1" cellpadding="5" cellspacing="0"
||'''Term''' || '''Option''' || '''Description'''
|-
|colspan=2|Description || A description of the trigger
|-
|colspan=2|SysCADTag || Any valid SysCAD tag. May have conversions.
|-
| rowspan="6" valign="top" | TriggerTest|| Rise = Value || The trigger will be true if the value has '''increased''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepRise = Value || The trigger will be true if the value has '''increased''' by more than the specified amount since the '''last step'''.
|-
|| Fall = Value || The trigger will be true if the value has '''decreased''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepFall = Value || The trigger will be true if the value has '''decreased''' by more than the specified amount since the '''last step'''.
|-
|| Delta = Value || The trigger will be true if the value has '''changed''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepDelta = Value || The trigger will be true if the value has '''changed''' by more than the specified amount since the '''last step'''.
|}
where = Value = Test value used to see where there are sudden changes.

'''Notes:'''
* Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
* If one or more Triggers are used, a period & offset is not relevant or required.
* If no triggers or period are specified then the table will not accumulate data.
* The smallest period that can be used is 1s. If the Dynamic timestep is less than 1s, and you want to record values at every iteration, a workaround is to use a Trigger on a tag which is changing every step, for example ''' $Solver.Dyn.Scenario.Elapsed.Time (ms)'''. Add the following line to the SAC file:

Trigger1 = Trigger1, $Solver.Dyn.Scenario.Elapsed.Time (ms), StepDelta=1e-05

== Field Options ==

The user may specify one or more fields in the table to be reported.

The fields are numbered and include five terms as described below, a field name, a SysCAD tag, a function, measure point and first point options.

{| border="1" cellpadding="5" cellspacing="0"
||'''Term''' || '''Option''' || '''Description'''
|-
|colspan=2|FieldName || Report column or field name. Should not contain characters: '.,[]
|-
|colspan=2|SysCADTag || Any valid SysCAD tag. May have conversions. '''If the tag is a string (eg TNK_001.Condition), use the String function below to ensure it is reported correctly.'''
|-
| rowspan="19" valign="top" | Function|| Current/Cur || Returns the current value.
|-
|| CurrentDiff/CurDiff || Returns the difference between current value and the current value at the end of the previous reporting period.
|-
|| Minimum/Min || Returns the minimum value for the chosen period.
|-
|| Maximum/Max || Returns the maximum value for the chosen period.
|-
|| Average/Avg || Returns the average value for the chosen period.
|-
|| AverageTotal/AvgTtl || Returns the average value since the beginning of the run.
|-
|| Sum || Returns the total of the reported tag for the report period. '''Note:''' The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)).
|-
|| SumTotal/SumTtl || Returns the total of the reported tag since the beginning of the run. '''Note:''' The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)).
|-
|| ReportTime || Returns the number of seconds for the report period. This will be equal to the number of steps in the report period multiplied by the timestep. Any valid SysCAD tag can be specified.
|-
|| SimulationTime || Returns the number of seconds since the beginning of the run. This will be equal to the total number of steps since the beginning of the run multiplied by the timestep. Any valid SysCAD tag can be specified.
|-
|| Time(operator,value,[timeunit]) || Returns the amount of time in the report period that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeTotal(operator,value,[timeunit]) /TimeTtl(operator,value,[timeunit]) || Returns the amount of time since the beginning of the run that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeInRange(low operator,low value,high operator,high value,[timeunit]) || Returns the amount of time in the report period that the reported tag is '''within''' the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeInRangeTotal(low operator,low value,high operator,high value,[timeunit]) || Returns the amount of time since the beginning of the run that the reported tag is '''within''' the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeOutRange(low operator,low value,high operator,high value,[timeunit])|| Returns the amount of time in the report period that the reported tag is '''outside''' the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeOutRangeTotal(low operator,low value,high operator,high value,[timeunit])|| Returns the amount of time since the beginning of the run that the reported tag is '''outside''' the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| Count/Cnt || Returns the number of recorded values for the report period. This will be equal to the number of steps in the report period. Any valid SysCAD tag can be specified.
|-
|| ChangeCount/ChgCnt || Returns the number of times the reported tag changed by more than 0.001 (in SI Units) during the report period.
|-
|| String/Str || Returns the current value of a string. '''Note:''' the SysCAD tag must be a string.
|-
| rowspan="3" valign="top" | MeasurePt || StartPt || The value of the SysCAD tag at the beginning of a step.
|-
|| EndPt || The value of the SysCAD tag at the end of a step.
|-
|| MidPt || The value of the SysCAD tag halfway through the step.
|-
| rowspan="2" valign="top" | FirstPoint || IgnoreFirst || Ignores the first value at the start of the run. i.e if the first value for the tank is 0 and it goes to 29 at the end of the first step, 29 will be recorded as the first value if the IgnoreFirst option is used.
|-
|| UseFirst || Use the first value at the start of the run.
|}

== Archive Options ==

To see the Archive Options dialog box, go to ''Tools - Archive Options''.

The Archive Options dialog box shows the tables that have been created and their frequency of data recording. The following dialog box is generated using the example described above.

[[Image:Archive Options.png]]
[[Image:Archive Options2.png]]

== Example Archive Enabled Projects ==

A few example projects with Archive enabled are included with the standard install. These include:

*[[Planning Example Project]]
*[[Tailings Dam Example Project]]
*[[Waste Handling with Batch Digestion Example Project]]

Archive Reporter

2026-05-12T09:01:51Z

Rod.Stephenson: /* Reporting Options */

[[Category:Reports]]
{{Navigation|[[User Guide]]|[[Reports]]}}
{|border="1" cellpadding="5" cellspacing="0"
|-
!Width=300 font style="background: #ebebeb"|[[Archive Reporter]]
!Width=300 |[[Archive Editor]]
!Width=300 |[[Archive (sac) File Text Format]]
|}

'''Related Links:''' [[Planning Example Project]], [[Tailings Dam Example Project]], [[Waste Handling with Batch Digestion Example Project]]
----
{{TOC|x=20%}}
== Introduction ==

The '''Archive Reporter''' is used with Dynamic projects to report data directly to a database, CSV or text file while a project is running. This has some similarities with the SysCAD [[Historian]], however the archiver has significantly greater functionality so the use of the historian for reporting is not recommended.

The user specifies how many tables of data are required (maximum is 500), the frequency of reporting (each table may be reported at a user specified time) and the tags that are reported in each table. These settings are recorded in a text file by the Archive Editor. The maximum number of Fields (including [[#Time_Fields|Time Fields]]) in a Table is 2000 (for DB-SQLITE .db3 format) and 3000 (for csv format).

Please also note that this file is loaded (or reloaded) from the [[Project Settings]] Archive tab page, as shown in the sections below.

== Archive Configuration ==

To use the Archiver:
# Go to ''Edit - Project Settings''
# The dialog box shown below will be displayed
# Go to the ''Archive'' page and tick the 'On' box
# The SysCAD Archive Configuration (.sac) file will be created
# Click on the 'Edit' button to edit the Archive.sac file

[[Image:Project Settings-Archive.jpg]]

The Settings are explained in the table below:

{| border="1" cellpadding="5" cellspacing="0"
|'''Setting / Tick Box''' || '''Description'''
|-
| colspan="2" font style="background: #ebebeb" |
=== Archive Reporter Configuration ===
|-
| On || The user must tick this box to enable the Archive Reporter.
|-
|| Name || This will be the name of the Archive Reporter file. The default name is Archive.sac and it is automatically created in the project folder when the user ticks the 'On' box. Users can choose to have a different file name but only one sac file can be used per project.
|-
| Browse || The user may browse for an alternative Archive file using this button.
|}

Press the '''Edit''' button to launch the Archive Editor.

Pressing the '''Reload''' button loads the Archive.sac file into SysCAD, which will check the file and display messages in the Messages window.

== System Settings ==

The Settings are explained in the table below:

{| border="1" cellpadding="5" cellspacing="0"
|'''Setting / Tick Box''' || '''Description'''
|-
| colspan="2" font style="background: #ebebeb" |
=== Time Fields ===
|-
| Date and Time || Every table will contain a column with the simulation time and date for the reported values. The format for this column will be Date:Time
|-
| Date Only || Every table will contain a column with the simulation date for the reported values.
|-
| Time Only || Every table will contain a column with the simulation time for the reported values.
|-
| Elapsed as HMS || Every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be hh:mm:ss
|-
| Elapsed Time || Unless the user selects 'Off', every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be a single value, and will display the total elapsed time as seconds, minutes, hours or days, depending on the user selection.
|-
| colspan="2" font style="background: #ebebeb" |

=== System Tables ===
|-
| Message Log || If the user ticks this box, all simulation messages will be written to a log file in the Archive folder.
|-
| Event Log || If the user ticks this box, all Events will be written to a log file in the Archive folder.
|-
| colspan="2" font style="background: #ebebeb" | ''Standard Fields'' These tick boxes determine what information is written to the Message Log file.
|-
| Source || The source of the message will be logged.
|-
| Tag || The unit tag that is source of the message will be logged.
|-
| Command || All SysCAD commands will be logged, e.g. 'Stop', 'Run', etc.
|-
| Type || The type of message will be logged, i.e. Error, Warning, etc.
|-
| Message || Messages will be displayed. If this is not ticked, then only Errors and Warnings will be logged.
|-
| ID No || The ID of the message will be logged.
|-
| Iteration || The Iteration of the message will be logged.
|-
| Call No || The Call number for the message will be logged.
|-
| Sequence No || The Sequence number of the message will be logged.
|}

== Reporting Options ==

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Option''' || '''Description'''
|-
|colspan=2| On || If On = 1, the table will be created. If On = 0, the table will not be created.
|-
|colspan=2| Name || The name of the table (for DB formats) or name of the file for csv/txt file formats.
|-
| rowspan="4" valign="top" | Format || DB-SQLITE || Data will be saved in Archive.db3 SQ Lite database in the project folder (Maximum fields per table is 2000)
|-
|| CSV || Data will be saved in a CSV file (Maximum fields per table is 3000)
|-
|| TXT || Data will be saved in a Text (txt) file
|-
| rowspan="2" valign="top" | Clear || Rewind || Clear archive file on next run.
|-
|| False || Add to existing archive file on next run. This can be overridden by other settings on the [[Solver Setting - Scenario]] page such as the RestartArchive option.
|}

'''Note:''' Each table can only have one format but within the same archive file, different tables can have different formats 

=== CSV and TXT File Options ===

If the Format chosen is CSV or TXT, then the following options are relevant.

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Description'''
|-
|Path || The path and folder name for storing CSV & TXT files (usually with the Project)
|-
|SigDigits || The number of significant digits for the tags that are reported to CSV & TXT files. Recommendation is 16. Accepted range is 2-17.
|}

=== Period and Offset ===

The Period and Offset for reporting can be specified. This is not required if the user specifies a Trigger, but note that both Periods and Triggers can be used for the same table.

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Description'''
|-
|| Period || Time frequency for reporting fields, where time zero is at start. '''Note 1:''' The period is relative to midnight, not the simulation start time. '''Note 2:''' If the period is not divisible by 24 hours, the reporting will not be at the same time each day.
|-
|| Offset || Time offset within the specified period. This affects when the first set of data is recorded. '''Note:''' The offset is relative to midnight, not the simulation start time.
|}

'''Notes:'''
* Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
* If one or more Triggers are used, a period & offset is not relevant or required.
* If no triggers or period are specified then the table will not accumulate data.
* Note that period and offset are relative to midnight. If your start time is not on a reporting period relative to midnight AND you want to report relative to the start time, then you need to specify an offset to achieve this. For example, if you want to report every 24 hours and the start time is 8:00am, then the offset should be 8 hours.

== Trigger Options ==

The user may specify one or more Triggers that will cause the values in the table to be reported. There can be any number of triggers. If the conditions of any of the triggers are met, then the fields will be reported.

The triggers are numbered and include three terms as described below, a description, a SysCAD tag and the Trigger Test.

{| border="1" cellpadding="5" cellspacing="0"
||'''Term''' || '''Option''' || '''Description'''
|-
|colspan=2|Description || A description of the trigger
|-
|colspan=2|SysCADTag || Any valid SysCAD tag. May have conversions.
|-
| rowspan="6" valign="top" | TriggerTest|| Rise = Value || The trigger will be true if the value has '''increased''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepRise = Value || The trigger will be true if the value has '''increased''' by more than the specified amount since the '''last step'''.
|-
|| Fall = Value || The trigger will be true if the value has '''decreased''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepFall = Value || The trigger will be true if the value has '''decreased''' by more than the specified amount since the '''last step'''.
|-
|| Delta = Value || The trigger will be true if the value has '''changed''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepDelta = Value || The trigger will be true if the value has '''changed''' by more than the specified amount since the '''last step'''.
|}
where = Value = Test value used to see where there are sudden changes.

'''Notes:'''
* Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
* If one or more Triggers are used, a period & offset is not relevant or required.
* If no triggers or period are specified then the table will not accumulate data.
* The smallest period that can be used is 1s. If the Dynamic timestep is less than 1s, and you want to record values at every iteration, a workaround is to use a Trigger on a tag which is changing every step, for example ''' $Solver.Dyn.Scenario.Elapsed.Time (ms)'''. Add the following line to the SAC file:

Trigger1 = Trigger1, $Solver.Dyn.Scenario.Elapsed.Time (ms), StepDelta=1e-05

== Field Options ==

The user may specify one or more fields in the table to be reported.

The fields are numbered and include five terms as described below, a field name, a SysCAD tag, a function, measure point and first point options.

{| border="1" cellpadding="5" cellspacing="0"
||'''Term''' || '''Option''' || '''Description'''
|-
|colspan=2|FieldName || Report column or field name. Should not contain characters: '.,[]
|-
|colspan=2|SysCADTag || Any valid SysCAD tag. May have conversions. '''If the tag is a string (eg TNK_001.Condition), use the String function below to ensure it is reported correctly.'''
|-
| rowspan="19" valign="top" | Function|| Current/Cur || Returns the current value.
|-
|| CurrentDiff/CurDiff || Returns the difference between current value and the current value at the end of the previous reporting period.
|-
|| Minimum/Min || Returns the minimum value for the chosen period.
|-
|| Maximum/Max || Returns the maximum value for the chosen period.
|-
|| Average/Avg || Returns the average value for the chosen period.
|-
|| AverageTotal/AvgTtl || Returns the average value since the beginning of the run.
|-
|| Sum || Returns the total of the reported tag for the report period. '''Note:''' The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)).
|-
|| SumTotal/SumTtl || Returns the total of the reported tag since the beginning of the run. '''Note:''' The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)).
|-
|| ReportTime || Returns the number of seconds for the report period. This will be equal to the number of steps in the report period multiplied by the timestep. Any valid SysCAD tag can be specified.
|-
|| SimulationTime || Returns the number of seconds since the beginning of the run. This will be equal to the total number of steps since the beginning of the run multiplied by the timestep. Any valid SysCAD tag can be specified.
|-
|| Time(operator,value,[timeunit]) || Returns the amount of time in the report period that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeTotal(operator,value,[timeunit]) /TimeTtl(operator,value,[timeunit]) || Returns the amount of time since the beginning of the run that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeInRange(low operator,low value,high operator,high value,[timeunit]) || Returns the amount of time in the report period that the reported tag is '''within''' the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeInRangeTotal(low operator,low value,high operator,high value,[timeunit]) || Returns the amount of time since the beginning of the run that the reported tag is '''within''' the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeOutRange(low operator,low value,high operator,high value,[timeunit])|| Returns the amount of time in the report period that the reported tag is '''outside''' the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeOutRangeTotal(low operator,low value,high operator,high value,[timeunit])|| Returns the amount of time since the beginning of the run that the reported tag is '''outside''' the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| Count/Cnt || Returns the number of recorded values for the report period. This will be equal to the number of steps in the report period. Any valid SysCAD tag can be specified.
|-
|| ChangeCount/ChgCnt || Returns the number of times the reported tag changed by more than 0.001 (in SI Units) during the report period.
|-
|| String/Str || Returns the current value of a string. '''Note:''' the SysCAD tag must be a string.
|-
| rowspan="3" valign="top" | MeasurePt || StartPt || The value of the SysCAD tag at the beginning of a step.
|-
|| EndPt || The value of the SysCAD tag at the end of a step.
|-
|| MidPt || The value of the SysCAD tag halfway through the step.
|-
| rowspan="2" valign="top" | FirstPoint || IgnoreFirst || Ignores the first value at the start of the run. i.e if the first value for the tank is 0 and it goes to 29 at the end of the first step, 29 will be recorded as the first value if the IgnoreFirst option is used.
|-
|| UseFirst || Use the first value at the start of the run.
|}

== Archive Options ==

To see the Archive Options dialog box, go to ''Tools - Archive Options''.

The Archive Options dialog box shows the tables that have been created and their frequency of data recording. The following dialog box is generated using the example described above.

[[Image:Archive Options.png]]
[[Image:Archive Options2.png]]

== Example Archive Enabled Projects ==

A few example projects with Archive enabled are included with the standard install. These include:

*[[Planning Example Project]]
*[[Tailings Dam Example Project]]
*[[Waste Handling with Batch Digestion Example Project]]

Archive Reporter

2026-04-27T14:57:29Z

Rod.Stephenson: /* Trigger Options */

[[Category:Reports]]
{{Navigation|[[User Guide]]|[[Reports]]}}
{|border="1" cellpadding="5" cellspacing="0"
|-
!Width=300 font style="background: #ebebeb"|[[Archive Reporter]]
!Width=300 |[[Archive Editor]]
!Width=300 |[[Archive (sac) File Text Format]]
|}

'''Related Links:''' [[Planning Example Project]], [[Tailings Dam Example Project]], [[Waste Handling with Batch Digestion Example Project]]
----
{{TOC|x=20%}}
== Introduction ==

The '''Archive Reporter''' is used with Dynamic projects to report data directly to a database, CSV or text file while a project is running. This has some similarities with the SysCAD [[Historian]], however the archiver has significantly greater functionality so the use of the historian for reporting is not recommended.

The user specifies how many tables of data are required (maximum is 500), the frequency of reporting (each table may be reported at a user specified time) and the tags that are reported in each table. These settings are recorded in a text file by the Archive Editor. The maximum number of Fields (including [[#Time_Fields|Time Fields]]) in a Table is 2000 (for DB-SQLITE .db3 format) and 3000 (for csv format).

Please also note that this file is loaded (or reloaded) from the [[Project Settings]] Archive tab page, as shown in the sections below.

== Archive Configuration ==

To use the Archiver:
# Go to ''Edit - Project Settings''
# The dialog box shown below will be displayed
# Go to the ''Archive'' page and tick the 'On' box
# The SysCAD Archive Configuration (.sac) file will be created
# Click on the 'Edit' button to edit the Archive.sac file

[[Image:Project Settings-Archive.jpg]]

The Settings are explained in the table below:

{| border="1" cellpadding="5" cellspacing="0"
|'''Setting / Tick Box''' || '''Description'''
|-
| colspan="2" font style="background: #ebebeb" |
=== Archive Reporter Configuration ===
|-
| On || The user must tick this box to enable the Archive Reporter.
|-
|| Name || This will be the name of the Archive Reporter file. The default name is Archive.sac and it is automatically created in the project folder when the user ticks the 'On' box. Users can choose to have a different file name but only one sac file can be used per project.
|-
| Browse || The user may browse for an alternative Archive file using this button.
|}

Press the '''Edit''' button to launch the Archive Editor.

Pressing the '''Reload''' button loads the Archive.sac file into SysCAD, which will check the file and display messages in the Messages window.

== System Settings ==

The Settings are explained in the table below:

{| border="1" cellpadding="5" cellspacing="0"
|'''Setting / Tick Box''' || '''Description'''
|-
| colspan="2" font style="background: #ebebeb" |
=== Time Fields ===
|-
| Date and Time || Every table will contain a column with the simulation time and date for the reported values. The format for this column will be Date:Time
|-
| Date Only || Every table will contain a column with the simulation date for the reported values.
|-
| Time Only || Every table will contain a column with the simulation time for the reported values.
|-
| Elapsed as HMS || Every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be hh:mm:ss
|-
| Elapsed Time || Unless the user selects 'Off', every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be a single value, and will display the total elapsed time as seconds, minutes, hours or days, depending on the user selection.
|-
| colspan="2" font style="background: #ebebeb" |

=== System Tables ===
|-
| Message Log || If the user ticks this box, all simulation messages will be written to a log file in the Archive folder.
|-
| Event Log || If the user ticks this box, all Events will be written to a log file in the Archive folder.
|-
| colspan="2" font style="background: #ebebeb" | ''Standard Fields'' These tick boxes determine what information is written to the Message Log file.
|-
| Source || The source of the message will be logged.
|-
| Tag || The unit tag that is source of the message will be logged.
|-
| Command || All SysCAD commands will be logged, e.g. 'Stop', 'Run', etc.
|-
| Type || The type of message will be logged, i.e. Error, Warning, etc.
|-
| Message || Messages will be displayed. If this is not ticked, then only Errors and Warnings will be logged.
|-
| ID No || The ID of the message will be logged.
|-
| Iteration || The Iteration of the message will be logged.
|-
| Call No || The Call number for the message will be logged.
|-
| Sequence No || The Sequence number of the message will be logged.
|}

== Reporting Options ==

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Option''' || '''Description'''
|-
|colspan=2| On || If On = 1, the table will be created. If On = 0, the table will not be created.
|-
|colspan=2| Name || The name of the table (for DB formats) or name of the file for csv/txt file formats.
|-
| rowspan="4" valign="top" | Format || DB-SQLITE || Data will be saved in Archive.db3 SQ Lite database in the project folder (Maximum fields per table is 2000)
|-
|| DB-MSACCESS || Data will be saved in Archive.mdb Microsoft Access database in the project folder
|-
|| CSV || Data will be saved in a CSV file (Maximum fields per table is 3000)
|-
|| TXT || Data will be saved in a Text (txt) file
|-
| rowspan="2" valign="top" | Clear || Rewind || Clear archive file on next run.
|-
|| False || Add to existing archive file on next run. This can be overridden by other settings on the [[Solver Setting - Scenario]] page such as the RestartArchive option.
|}

'''Note:''' Each table can only have one format but within the same archive file, different tables can have different formats 

=== CSV and TXT File Options ===

If the Format chosen is CSV or TXT, then the following options are relevant.

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Description'''
|-
|Path || The path and folder name for storing CSV & TXT files (usually with the Project)
|-
|SigDigits || The number of significant digits for the tags that are reported to CSV & TXT files. Recommendation is 16. Accepted range is 2-17.
|}

=== Period and Offset ===

The Period and Offset for reporting can be specified. This is not required if the user specifies a Trigger, but note that both Periods and Triggers can be used for the same table.

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Description'''
|-
|| Period || Time frequency for reporting fields, where time zero is at start. '''Note 1:''' The period is relative to midnight, not the simulation start time. '''Note 2:''' If the period is not divisible by 24 hours, the reporting will not be at the same time each day.
|-
|| Offset || Time offset within the specified period. This affects when the first set of data is recorded. '''Note:''' The offset is relative to midnight, not the simulation start time.
|}

'''Notes:'''
* Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
* If one or more Triggers are used, a period & offset is not relevant or required.
* If no triggers or period are specified then the table will not accumulate data.
* Note that period and offset are relative to midnight. If your start time is not on a reporting period relative to midnight AND you want to report relative to the start time, then you need to specify an offset to achieve this. For example, if you want to report every 24 hours and the start time is 8:00am, then the offset should be 8 hours.

== Trigger Options ==

The user may specify one or more Triggers that will cause the values in the table to be reported. There can be any number of triggers. If the conditions of any of the triggers are met, then the fields will be reported.

The triggers are numbered and include three terms as described below, a description, a SysCAD tag and the Trigger Test.

{| border="1" cellpadding="5" cellspacing="0"
||'''Term''' || '''Option''' || '''Description'''
|-
|colspan=2|Description || A description of the trigger
|-
|colspan=2|SysCADTag || Any valid SysCAD tag. May have conversions.
|-
| rowspan="6" valign="top" | TriggerTest|| Rise = Value || The trigger will be true if the value has '''increased''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepRise = Value || The trigger will be true if the value has '''increased''' by more than the specified amount since the '''last step'''.
|-
|| Fall = Value || The trigger will be true if the value has '''decreased''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepFall = Value || The trigger will be true if the value has '''decreased''' by more than the specified amount since the '''last step'''.
|-
|| Delta = Value || The trigger will be true if the value has '''changed''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepDelta = Value || The trigger will be true if the value has '''changed''' by more than the specified amount since the '''last step'''.
|}
where = Value = Test value used to see where there are sudden changes.

'''Notes:'''
* Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
* If one or more Triggers are used, a period & offset is not relevant or required.
* If no triggers or period are specified then the table will not accumulate data.
* The smallest period that can be used is 1s. If the Dynamic timestep is less than 1s, and you want to record values at every iteration, a workaround is to use a Trigger on a tag which is changing every step, for example ''' $Solver.Dyn.Scenario.Elapsed.Time (ms)'''. Add the following line to the SAC file:

Trigger1 = Trigger1, $Solver.Dyn.Scenario.Elapsed.Time (ms), StepDelta=1e-05

== Field Options ==

The user may specify one or more fields in the table to be reported.

The fields are numbered and include five terms as described below, a field name, a SysCAD tag, a function, measure point and first point options.

{| border="1" cellpadding="5" cellspacing="0"
||'''Term''' || '''Option''' || '''Description'''
|-
|colspan=2|FieldName || Report column or field name. Should not contain characters: '.,[]
|-
|colspan=2|SysCADTag || Any valid SysCAD tag. May have conversions. '''If the tag is a string (eg TNK_001.Condition), use the String function below to ensure it is reported correctly.'''
|-
| rowspan="19" valign="top" | Function|| Current/Cur || Returns the current value.
|-
|| CurrentDiff/CurDiff || Returns the difference between current value and the current value at the end of the previous reporting period.
|-
|| Minimum/Min || Returns the minimum value for the chosen period.
|-
|| Maximum/Max || Returns the maximum value for the chosen period.
|-
|| Average/Avg || Returns the average value for the chosen period.
|-
|| AverageTotal/AvgTtl || Returns the average value since the beginning of the run.
|-
|| Sum || Returns the total of the reported tag for the report period. '''Note:''' The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)).
|-
|| SumTotal/SumTtl || Returns the total of the reported tag since the beginning of the run. '''Note:''' The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)).
|-
|| ReportTime || Returns the number of seconds for the report period. This will be equal to the number of steps in the report period multiplied by the timestep. Any valid SysCAD tag can be specified.
|-
|| SimulationTime || Returns the number of seconds since the beginning of the run. This will be equal to the total number of steps since the beginning of the run multiplied by the timestep. Any valid SysCAD tag can be specified.
|-
|| Time(operator,value,[timeunit]) || Returns the amount of time in the report period that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeTotal(operator,value,[timeunit]) /TimeTtl(operator,value,[timeunit]) || Returns the amount of time since the beginning of the run that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeInRange(low operator,low value,high operator,high value,[timeunit]) || Returns the amount of time in the report period that the reported tag is '''within''' the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeInRangeTotal(low operator,low value,high operator,high value,[timeunit]) || Returns the amount of time since the beginning of the run that the reported tag is '''within''' the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeOutRange(low operator,low value,high operator,high value,[timeunit])|| Returns the amount of time in the report period that the reported tag is '''outside''' the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeOutRangeTotal(low operator,low value,high operator,high value,[timeunit])|| Returns the amount of time since the beginning of the run that the reported tag is '''outside''' the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| Count/Cnt || Returns the number of recorded values for the report period. This will be equal to the number of steps in the report period. Any valid SysCAD tag can be specified.
|-
|| ChangeCount/ChgCnt || Returns the number of times the reported tag changed by more than 0.001 (in SI Units) during the report period.
|-
|| String/Str || Returns the current value of a string. '''Note:''' the SysCAD tag must be a string.
|-
| rowspan="3" valign="top" | MeasurePt || StartPt || The value of the SysCAD tag at the beginning of a step.
|-
|| EndPt || The value of the SysCAD tag at the end of a step.
|-
|| MidPt || The value of the SysCAD tag halfway through the step.
|-
| rowspan="2" valign="top" | FirstPoint || IgnoreFirst || Ignores the first value at the start of the run. i.e if the first value for the tank is 0 and it goes to 29 at the end of the first step, 29 will be recorded as the first value if the IgnoreFirst option is used.
|-
|| UseFirst || Use the first value at the start of the run.
|}

== Archive Options ==

To see the Archive Options dialog box, go to ''Tools - Archive Options''.

The Archive Options dialog box shows the tables that have been created and their frequency of data recording. The following dialog box is generated using the example described above.

[[Image:Archive Options.png]]
[[Image:Archive Options2.png]]

== Example Archive Enabled Projects ==

A few example projects with Archive enabled are included with the standard install. These include:

*[[Planning Example Project]]
*[[Tailings Dam Example Project]]
*[[Waste Handling with Batch Digestion Example Project]]

Archive Reporter

2026-04-27T14:56:18Z

Rod.Stephenson: /* Trigger Options */

[[Category:Reports]]
{{Navigation|[[User Guide]]|[[Reports]]}}
{|border="1" cellpadding="5" cellspacing="0"
|-
!Width=300 font style="background: #ebebeb"|[[Archive Reporter]]
!Width=300 |[[Archive Editor]]
!Width=300 |[[Archive (sac) File Text Format]]
|}

'''Related Links:''' [[Planning Example Project]], [[Tailings Dam Example Project]], [[Waste Handling with Batch Digestion Example Project]]
----
{{TOC|x=20%}}
== Introduction ==

The '''Archive Reporter''' is used with Dynamic projects to report data directly to a database, CSV or text file while a project is running. This has some similarities with the SysCAD [[Historian]], however the archiver has significantly greater functionality so the use of the historian for reporting is not recommended.

The user specifies how many tables of data are required (maximum is 500), the frequency of reporting (each table may be reported at a user specified time) and the tags that are reported in each table. These settings are recorded in a text file by the Archive Editor. The maximum number of Fields (including [[#Time_Fields|Time Fields]]) in a Table is 2000 (for DB-SQLITE .db3 format) and 3000 (for csv format).

Please also note that this file is loaded (or reloaded) from the [[Project Settings]] Archive tab page, as shown in the sections below.

== Archive Configuration ==

To use the Archiver:
# Go to ''Edit - Project Settings''
# The dialog box shown below will be displayed
# Go to the ''Archive'' page and tick the 'On' box
# The SysCAD Archive Configuration (.sac) file will be created
# Click on the 'Edit' button to edit the Archive.sac file

[[Image:Project Settings-Archive.jpg]]

The Settings are explained in the table below:

{| border="1" cellpadding="5" cellspacing="0"
|'''Setting / Tick Box''' || '''Description'''
|-
| colspan="2" font style="background: #ebebeb" |
=== Archive Reporter Configuration ===
|-
| On || The user must tick this box to enable the Archive Reporter.
|-
|| Name || This will be the name of the Archive Reporter file. The default name is Archive.sac and it is automatically created in the project folder when the user ticks the 'On' box. Users can choose to have a different file name but only one sac file can be used per project.
|-
| Browse || The user may browse for an alternative Archive file using this button.
|}

Press the '''Edit''' button to launch the Archive Editor.

Pressing the '''Reload''' button loads the Archive.sac file into SysCAD, which will check the file and display messages in the Messages window.

== System Settings ==

The Settings are explained in the table below:

{| border="1" cellpadding="5" cellspacing="0"
|'''Setting / Tick Box''' || '''Description'''
|-
| colspan="2" font style="background: #ebebeb" |
=== Time Fields ===
|-
| Date and Time || Every table will contain a column with the simulation time and date for the reported values. The format for this column will be Date:Time
|-
| Date Only || Every table will contain a column with the simulation date for the reported values.
|-
| Time Only || Every table will contain a column with the simulation time for the reported values.
|-
| Elapsed as HMS || Every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be hh:mm:ss
|-
| Elapsed Time || Unless the user selects 'Off', every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be a single value, and will display the total elapsed time as seconds, minutes, hours or days, depending on the user selection.
|-
| colspan="2" font style="background: #ebebeb" |

=== System Tables ===
|-
| Message Log || If the user ticks this box, all simulation messages will be written to a log file in the Archive folder.
|-
| Event Log || If the user ticks this box, all Events will be written to a log file in the Archive folder.
|-
| colspan="2" font style="background: #ebebeb" | ''Standard Fields'' These tick boxes determine what information is written to the Message Log file.
|-
| Source || The source of the message will be logged.
|-
| Tag || The unit tag that is source of the message will be logged.
|-
| Command || All SysCAD commands will be logged, e.g. 'Stop', 'Run', etc.
|-
| Type || The type of message will be logged, i.e. Error, Warning, etc.
|-
| Message || Messages will be displayed. If this is not ticked, then only Errors and Warnings will be logged.
|-
| ID No || The ID of the message will be logged.
|-
| Iteration || The Iteration of the message will be logged.
|-
| Call No || The Call number for the message will be logged.
|-
| Sequence No || The Sequence number of the message will be logged.
|}

== Reporting Options ==

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Option''' || '''Description'''
|-
|colspan=2| On || If On = 1, the table will be created. If On = 0, the table will not be created.
|-
|colspan=2| Name || The name of the table (for DB formats) or name of the file for csv/txt file formats.
|-
| rowspan="4" valign="top" | Format || DB-SQLITE || Data will be saved in Archive.db3 SQ Lite database in the project folder (Maximum fields per table is 2000)
|-
|| DB-MSACCESS || Data will be saved in Archive.mdb Microsoft Access database in the project folder
|-
|| CSV || Data will be saved in a CSV file (Maximum fields per table is 3000)
|-
|| TXT || Data will be saved in a Text (txt) file
|-
| rowspan="2" valign="top" | Clear || Rewind || Clear archive file on next run.
|-
|| False || Add to existing archive file on next run. This can be overridden by other settings on the [[Solver Setting - Scenario]] page such as the RestartArchive option.
|}

'''Note:''' Each table can only have one format but within the same archive file, different tables can have different formats 

=== CSV and TXT File Options ===

If the Format chosen is CSV or TXT, then the following options are relevant.

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Description'''
|-
|Path || The path and folder name for storing CSV & TXT files (usually with the Project)
|-
|SigDigits || The number of significant digits for the tags that are reported to CSV & TXT files. Recommendation is 16. Accepted range is 2-17.
|}

=== Period and Offset ===

The Period and Offset for reporting can be specified. This is not required if the user specifies a Trigger, but note that both Periods and Triggers can be used for the same table.

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Description'''
|-
|| Period || Time frequency for reporting fields, where time zero is at start. '''Note 1:''' The period is relative to midnight, not the simulation start time. '''Note 2:''' If the period is not divisible by 24 hours, the reporting will not be at the same time each day.
|-
|| Offset || Time offset within the specified period. This affects when the first set of data is recorded. '''Note:''' The offset is relative to midnight, not the simulation start time.
|}

'''Notes:'''
* Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
* If one or more Triggers are used, a period & offset is not relevant or required.
* If no triggers or period are specified then the table will not accumulate data.
* Note that period and offset are relative to midnight. If your start time is not on a reporting period relative to midnight AND you want to report relative to the start time, then you need to specify an offset to achieve this. For example, if you want to report every 24 hours and the start time is 8:00am, then the offset should be 8 hours.

== Trigger Options ==

The user may specify one or more Triggers that will cause the values in the table to be reported. There can be any number of triggers. If the conditions of any of the triggers are met, then the fields will be reported.

The triggers are numbered and include three terms as described below, a description, a SysCAD tag and the Trigger Test.

{| border="1" cellpadding="5" cellspacing="0"
||'''Term''' || '''Option''' || '''Description'''
|-
|colspan=2|Description || A description of the trigger
|-
|colspan=2|SysCADTag || Any valid SysCAD tag. May have conversions.
|-
| rowspan="6" valign="top" | TriggerTest|| Rise = Value || The trigger will be true if the value has '''increased''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepRise = Value || The trigger will be true if the value has '''increased''' by more than the specified amount since the '''last step'''.
|-
|| Fall = Value || The trigger will be true if the value has '''decreased''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepFall = Value || The trigger will be true if the value has '''decreased''' by more than the specified amount since the '''last step'''.
|-
|| Delta = Value || The trigger will be true if the value has '''changed''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepDelta = Value || The trigger will be true if the value has '''changed''' by more than the specified amount since the '''last step'''.
|}
where = Value = Test value used to see where there are sudden changes.

'''Notes:'''
* Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
* If one or more Triggers are used, a period & offset is not relevant or required.
* If no triggers or period are specified then the table will not accumulate data.
* The smallest period that can be used is 1s. If the Dynamic timestep is less than 1s, and you want to record values at every iteration, a workaround is to use a Trigger on a tag which is changing every step, for example ''' $Solver.Dyn.Scenario.Elapsed.Time (ms)'''

== Field Options ==

The user may specify one or more fields in the table to be reported.

The fields are numbered and include five terms as described below, a field name, a SysCAD tag, a function, measure point and first point options.

{| border="1" cellpadding="5" cellspacing="0"
||'''Term''' || '''Option''' || '''Description'''
|-
|colspan=2|FieldName || Report column or field name. Should not contain characters: '.,[]
|-
|colspan=2|SysCADTag || Any valid SysCAD tag. May have conversions. '''If the tag is a string (eg TNK_001.Condition), use the String function below to ensure it is reported correctly.'''
|-
| rowspan="19" valign="top" | Function|| Current/Cur || Returns the current value.
|-
|| CurrentDiff/CurDiff || Returns the difference between current value and the current value at the end of the previous reporting period.
|-
|| Minimum/Min || Returns the minimum value for the chosen period.
|-
|| Maximum/Max || Returns the maximum value for the chosen period.
|-
|| Average/Avg || Returns the average value for the chosen period.
|-
|| AverageTotal/AvgTtl || Returns the average value since the beginning of the run.
|-
|| Sum || Returns the total of the reported tag for the report period. '''Note:''' The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)).
|-
|| SumTotal/SumTtl || Returns the total of the reported tag since the beginning of the run. '''Note:''' The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)).
|-
|| ReportTime || Returns the number of seconds for the report period. This will be equal to the number of steps in the report period multiplied by the timestep. Any valid SysCAD tag can be specified.
|-
|| SimulationTime || Returns the number of seconds since the beginning of the run. This will be equal to the total number of steps since the beginning of the run multiplied by the timestep. Any valid SysCAD tag can be specified.
|-
|| Time(operator,value,[timeunit]) || Returns the amount of time in the report period that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeTotal(operator,value,[timeunit]) /TimeTtl(operator,value,[timeunit]) || Returns the amount of time since the beginning of the run that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeInRange(low operator,low value,high operator,high value,[timeunit]) || Returns the amount of time in the report period that the reported tag is '''within''' the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeInRangeTotal(low operator,low value,high operator,high value,[timeunit]) || Returns the amount of time since the beginning of the run that the reported tag is '''within''' the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeOutRange(low operator,low value,high operator,high value,[timeunit])|| Returns the amount of time in the report period that the reported tag is '''outside''' the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeOutRangeTotal(low operator,low value,high operator,high value,[timeunit])|| Returns the amount of time since the beginning of the run that the reported tag is '''outside''' the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| Count/Cnt || Returns the number of recorded values for the report period. This will be equal to the number of steps in the report period. Any valid SysCAD tag can be specified.
|-
|| ChangeCount/ChgCnt || Returns the number of times the reported tag changed by more than 0.001 (in SI Units) during the report period.
|-
|| String/Str || Returns the current value of a string. '''Note:''' the SysCAD tag must be a string.
|-
| rowspan="3" valign="top" | MeasurePt || StartPt || The value of the SysCAD tag at the beginning of a step.
|-
|| EndPt || The value of the SysCAD tag at the end of a step.
|-
|| MidPt || The value of the SysCAD tag halfway through the step.
|-
| rowspan="2" valign="top" | FirstPoint || IgnoreFirst || Ignores the first value at the start of the run. i.e if the first value for the tank is 0 and it goes to 29 at the end of the first step, 29 will be recorded as the first value if the IgnoreFirst option is used.
|-
|| UseFirst || Use the first value at the start of the run.
|}

== Archive Options ==

To see the Archive Options dialog box, go to ''Tools - Archive Options''.

The Archive Options dialog box shows the tables that have been created and their frequency of data recording. The following dialog box is generated using the example described above.

[[Image:Archive Options.png]]
[[Image:Archive Options2.png]]

== Example Archive Enabled Projects ==

A few example projects with Archive enabled are included with the standard install. These include:

*[[Planning Example Project]]
*[[Tailings Dam Example Project]]
*[[Waste Handling with Batch Digestion Example Project]]

Archive Reporter

2026-04-27T14:55:33Z

Rod.Stephenson: /* Trigger Options */

[[Category:Reports]]
{{Navigation|[[User Guide]]|[[Reports]]}}
{|border="1" cellpadding="5" cellspacing="0"
|-
!Width=300 font style="background: #ebebeb"|[[Archive Reporter]]
!Width=300 |[[Archive Editor]]
!Width=300 |[[Archive (sac) File Text Format]]
|}

'''Related Links:''' [[Planning Example Project]], [[Tailings Dam Example Project]], [[Waste Handling with Batch Digestion Example Project]]
----
{{TOC|x=20%}}
== Introduction ==

The '''Archive Reporter''' is used with Dynamic projects to report data directly to a database, CSV or text file while a project is running. This has some similarities with the SysCAD [[Historian]], however the archiver has significantly greater functionality so the use of the historian for reporting is not recommended.

The user specifies how many tables of data are required (maximum is 500), the frequency of reporting (each table may be reported at a user specified time) and the tags that are reported in each table. These settings are recorded in a text file by the Archive Editor. The maximum number of Fields (including [[#Time_Fields|Time Fields]]) in a Table is 2000 (for DB-SQLITE .db3 format) and 3000 (for csv format).

Please also note that this file is loaded (or reloaded) from the [[Project Settings]] Archive tab page, as shown in the sections below.

== Archive Configuration ==

To use the Archiver:
# Go to ''Edit - Project Settings''
# The dialog box shown below will be displayed
# Go to the ''Archive'' page and tick the 'On' box
# The SysCAD Archive Configuration (.sac) file will be created
# Click on the 'Edit' button to edit the Archive.sac file

[[Image:Project Settings-Archive.jpg]]

The Settings are explained in the table below:

{| border="1" cellpadding="5" cellspacing="0"
|'''Setting / Tick Box''' || '''Description'''
|-
| colspan="2" font style="background: #ebebeb" |
=== Archive Reporter Configuration ===
|-
| On || The user must tick this box to enable the Archive Reporter.
|-
|| Name || This will be the name of the Archive Reporter file. The default name is Archive.sac and it is automatically created in the project folder when the user ticks the 'On' box. Users can choose to have a different file name but only one sac file can be used per project.
|-
| Browse || The user may browse for an alternative Archive file using this button.
|}

Press the '''Edit''' button to launch the Archive Editor.

Pressing the '''Reload''' button loads the Archive.sac file into SysCAD, which will check the file and display messages in the Messages window.

== System Settings ==

The Settings are explained in the table below:

{| border="1" cellpadding="5" cellspacing="0"
|'''Setting / Tick Box''' || '''Description'''
|-
| colspan="2" font style="background: #ebebeb" |
=== Time Fields ===
|-
| Date and Time || Every table will contain a column with the simulation time and date for the reported values. The format for this column will be Date:Time
|-
| Date Only || Every table will contain a column with the simulation date for the reported values.
|-
| Time Only || Every table will contain a column with the simulation time for the reported values.
|-
| Elapsed as HMS || Every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be hh:mm:ss
|-
| Elapsed Time || Unless the user selects 'Off', every table will contain a column with the elapsed simulation time for the reported values. The format for this column will be a single value, and will display the total elapsed time as seconds, minutes, hours or days, depending on the user selection.
|-
| colspan="2" font style="background: #ebebeb" |

=== System Tables ===
|-
| Message Log || If the user ticks this box, all simulation messages will be written to a log file in the Archive folder.
|-
| Event Log || If the user ticks this box, all Events will be written to a log file in the Archive folder.
|-
| colspan="2" font style="background: #ebebeb" | ''Standard Fields'' These tick boxes determine what information is written to the Message Log file.
|-
| Source || The source of the message will be logged.
|-
| Tag || The unit tag that is source of the message will be logged.
|-
| Command || All SysCAD commands will be logged, e.g. 'Stop', 'Run', etc.
|-
| Type || The type of message will be logged, i.e. Error, Warning, etc.
|-
| Message || Messages will be displayed. If this is not ticked, then only Errors and Warnings will be logged.
|-
| ID No || The ID of the message will be logged.
|-
| Iteration || The Iteration of the message will be logged.
|-
| Call No || The Call number for the message will be logged.
|-
| Sequence No || The Sequence number of the message will be logged.
|}

== Reporting Options ==

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Option''' || '''Description'''
|-
|colspan=2| On || If On = 1, the table will be created. If On = 0, the table will not be created.
|-
|colspan=2| Name || The name of the table (for DB formats) or name of the file for csv/txt file formats.
|-
| rowspan="4" valign="top" | Format || DB-SQLITE || Data will be saved in Archive.db3 SQ Lite database in the project folder (Maximum fields per table is 2000)
|-
|| DB-MSACCESS || Data will be saved in Archive.mdb Microsoft Access database in the project folder
|-
|| CSV || Data will be saved in a CSV file (Maximum fields per table is 3000)
|-
|| TXT || Data will be saved in a Text (txt) file
|-
| rowspan="2" valign="top" | Clear || Rewind || Clear archive file on next run.
|-
|| False || Add to existing archive file on next run. This can be overridden by other settings on the [[Solver Setting - Scenario]] page such as the RestartArchive option.
|}

'''Note:''' Each table can only have one format but within the same archive file, different tables can have different formats 

=== CSV and TXT File Options ===

If the Format chosen is CSV or TXT, then the following options are relevant.

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Description'''
|-
|Path || The path and folder name for storing CSV & TXT files (usually with the Project)
|-
|SigDigits || The number of significant digits for the tags that are reported to CSV & TXT files. Recommendation is 16. Accepted range is 2-17.
|}

=== Period and Offset ===

The Period and Offset for reporting can be specified. This is not required if the user specifies a Trigger, but note that both Periods and Triggers can be used for the same table.

{| border="1" cellpadding="5" cellspacing="0"
||'''Field''' || '''Description'''
|-
|| Period || Time frequency for reporting fields, where time zero is at start. '''Note 1:''' The period is relative to midnight, not the simulation start time. '''Note 2:''' If the period is not divisible by 24 hours, the reporting will not be at the same time each day.
|-
|| Offset || Time offset within the specified period. This affects when the first set of data is recorded. '''Note:''' The offset is relative to midnight, not the simulation start time.
|}

'''Notes:'''
* Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
* If one or more Triggers are used, a period & offset is not relevant or required.
* If no triggers or period are specified then the table will not accumulate data.
* Note that period and offset are relative to midnight. If your start time is not on a reporting period relative to midnight AND you want to report relative to the start time, then you need to specify an offset to achieve this. For example, if you want to report every 24 hours and the start time is 8:00am, then the offset should be 8 hours.

== Trigger Options ==

The user may specify one or more Triggers that will cause the values in the table to be reported. There can be any number of triggers. If the conditions of any of the triggers are met, then the fields will be reported.

The triggers are numbered and include three terms as described below, a description, a SysCAD tag and the Trigger Test.

{| border="1" cellpadding="5" cellspacing="0"
||'''Term''' || '''Option''' || '''Description'''
|-
|colspan=2|Description || A description of the trigger
|-
|colspan=2|SysCADTag || Any valid SysCAD tag. May have conversions.
|-
| rowspan="6" valign="top" | TriggerTest|| Rise = Value || The trigger will be true if the value has '''increased''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepRise = Value || The trigger will be true if the value has '''increased''' by more than the specified amount since the '''last step'''.
|-
|| Fall = Value || The trigger will be true if the value has '''decreased''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepFall = Value || The trigger will be true if the value has '''decreased''' by more than the specified amount since the '''last step'''.
|-
|| Delta = Value || The trigger will be true if the value has '''changed''' by more than the specified amount since the '''last recorded value'''. The last recorded value will either be the first value or the value when the trigger was last true.
|-
|| StepDelta = Value || The trigger will be true if the value has '''changed''' by more than the specified amount since the '''last step'''.
|}
where = Value = Test value used to see where there are sudden changes.

'''Notes:'''
* Use Period for reporting at fixed time intervals, OR use Triggers for reporting at irregular time intervals (i.e. report specified fields based on trigger logic).
* If one or more Triggers are used, a period & offset is not relevant or required.
* If no triggers or period are specified then the table will not accumulate data.
* The smallest period that can be used is 1s. If the Dynamic timestep is less than 1s, a workaround is to use a Trigger on a tag which is changing every step, for example ''' $Solver.Dyn.Scenario.Elapsed.Time (ms)'''

== Field Options ==

The user may specify one or more fields in the table to be reported.

The fields are numbered and include five terms as described below, a field name, a SysCAD tag, a function, measure point and first point options.

{| border="1" cellpadding="5" cellspacing="0"
||'''Term''' || '''Option''' || '''Description'''
|-
|colspan=2|FieldName || Report column or field name. Should not contain characters: '.,[]
|-
|colspan=2|SysCADTag || Any valid SysCAD tag. May have conversions. '''If the tag is a string (eg TNK_001.Condition), use the String function below to ensure it is reported correctly.'''
|-
| rowspan="19" valign="top" | Function|| Current/Cur || Returns the current value.
|-
|| CurrentDiff/CurDiff || Returns the difference between current value and the current value at the end of the previous reporting period.
|-
|| Minimum/Min || Returns the minimum value for the chosen period.
|-
|| Maximum/Max || Returns the maximum value for the chosen period.
|-
|| Average/Avg || Returns the average value for the chosen period.
|-
|| AverageTotal/AvgTtl || Returns the average value since the beginning of the run.
|-
|| Sum || Returns the total of the reported tag for the report period. '''Note:''' The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)).
|-
|| SumTotal/SumTtl || Returns the total of the reported tag since the beginning of the run. '''Note:''' The SysCAD tag MUST be on a per second basis (e.g. P_1.Qm (t/s)).
|-
|| ReportTime || Returns the number of seconds for the report period. This will be equal to the number of steps in the report period multiplied by the timestep. Any valid SysCAD tag can be specified.
|-
|| SimulationTime || Returns the number of seconds since the beginning of the run. This will be equal to the total number of steps since the beginning of the run multiplied by the timestep. Any valid SysCAD tag can be specified.
|-
|| Time(operator,value,[timeunit]) || Returns the amount of time in the report period that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeTotal(operator,value,[timeunit]) /TimeTtl(operator,value,[timeunit]) || Returns the amount of time since the beginning of the run that the reported tag meets the condition specified using operator and value. Valid operators are <, <=, ==, <>, >= and >. Value can be any number. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeInRange(low operator,low value,high operator,high value,[timeunit]) || Returns the amount of time in the report period that the reported tag is '''within''' the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeInRangeTotal(low operator,low value,high operator,high value,[timeunit]) || Returns the amount of time since the beginning of the run that the reported tag is '''within''' the range specified. Valid low operators are > and >=. Valid high operators are < and <=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeOutRange(low operator,low value,high operator,high value,[timeunit])|| Returns the amount of time in the report period that the reported tag is '''outside''' the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| TimeOutRangeTotal(low operator,low value,high operator,high value,[timeunit])|| Returns the amount of time since the beginning of the run that the reported tag is '''outside''' the range specified. Valid low operators are < and <=. Valid high operators are > and >=. Low value and high value can be any numbers. Timeunit is optional (default is seconds), options are s, m, h or d.
|-
|| Count/Cnt || Returns the number of recorded values for the report period. This will be equal to the number of steps in the report period. Any valid SysCAD tag can be specified.
|-
|| ChangeCount/ChgCnt || Returns the number of times the reported tag changed by more than 0.001 (in SI Units) during the report period.
|-
|| String/Str || Returns the current value of a string. '''Note:''' the SysCAD tag must be a string.
|-
| rowspan="3" valign="top" | MeasurePt || StartPt || The value of the SysCAD tag at the beginning of a step.
|-
|| EndPt || The value of the SysCAD tag at the end of a step.
|-
|| MidPt || The value of the SysCAD tag halfway through the step.
|-
| rowspan="2" valign="top" | FirstPoint || IgnoreFirst || Ignores the first value at the start of the run. i.e if the first value for the tank is 0 and it goes to 29 at the end of the first step, 29 will be recorded as the first value if the IgnoreFirst option is used.
|-
|| UseFirst || Use the first value at the start of the run.
|}

== Archive Options ==

To see the Archive Options dialog box, go to ''Tools - Archive Options''.

The Archive Options dialog box shows the tables that have been created and their frequency of data recording. The following dialog box is generated using the example described above.

[[Image:Archive Options.png]]
[[Image:Archive Options2.png]]

== Example Archive Enabled Projects ==

A few example projects with Archive enabled are included with the standard install. These include:

*[[Planning Example Project]]
*[[Tailings Dam Example Project]]
*[[Waste Handling with Batch Digestion Example Project]]

File:Ctrlvol.png

2026-04-27T12:23:53Z

Rod.Stephenson: