A vector is a special type of STRUCT that has an array as its value. It allows you to read values from and write values to an array in the database. It also allows you to define the source of array values for use by methods that require array values, such as the Set Forecast method. To use a vector in an ST program, you need to use the VECTOR keyword.
Vectors are similar to arrays, except that they have three properties:
- Capacity—The maximum number of values that can be read/written by the vector
- Length—The actual number of values that are read/written by the vector. This can be defined in the declaration or will be calculated automatically.
- Value—The array of the vector. The vector's array will use values that are read from an array in the database, such as an array variable database item.
The syntax for a vector is:
VECTOR[value range] OF <Value Type>;
Where:
- VECTOR is the keyword
- [value range] is the maximum number of values that can be read or written. For the value range, you have to start with 0 (the first value) and end with the number of the last permitted value. Use two points between the first and last values, for example, [0..99] sets the value range to 100 values (0 being the first value, 99 the hundredth value).
- OF <Value Type> defines the value type of the direct variable that is read or is being written to. For example, OF UDINT; or OF DINT;
For example:
VAR
V AT %M(.Values) : VECTOR[0..99] OF DINT;
END_VAR
Sets the V variable to represent the vector. The source of the vector's array is defined as the database item named 'Values', and the capacity of the vector is defined as [0..99]. The value type of the vector's array is set to DINT. This means that the Capacity property of the vector is set to 100 (0 to 99 inclusive) and the Value property is set to reference the array of the 'Values' database item. The Length is not defined, but will be calculated automatically - it will match the number of values that are actually read from the 'Values' item's array. So, if there are 10 values in the array, the Length will be set to 10.
You can also write to the properties of a vector in the same way as you would write to the properties of any item, for example, you can set the Length of a vector by using <variable>.length := <length value>. Where <variable> is the name of the variable that represents the vector and <length value> is the number value for the length or is a calculation to determine the length.
VAR
V AT %M(.Values) : VECTOR[0..99] OF DINT;
END_VAR
V.Length := 6;
In the example above, the Length of the vector is set to 6 so that only 6 values are read from or written to the array.
The Capacity property of a vector is read-only.
Example 1 - Using a Vector to Read from an Array
The following example shows how the VECTOR keyword can be used in an ST program that reads from an array and uses the array values to calculate an average value.
PROGRAM CalculateAverage
VAR
Values AT %M(.Values) : VECTOR[0..99] OF DINT;
Average AT %M(.Average) : LREAL;
END_VAR
VAR
Sum : DINT;
END_VAR
Sum:= 0;
FOR I :=0 TO Values.Length - 1 DO
Sum := Sum + Values.Value[I];
END_FOR;
Average := DINT_TO_LREAL(Sum) / DINT_TO_LREAL(Values.Length);
END_PROGRAM
In this program, the variable named Values can read to and write from the direct variable named Values (which is a variable array database item). As the direct variable is an array, a vector is used to read and write the values. The VECTOR keyword is used and has a value range of one hundred values (0..99).The value range is the capacity of the vector. The value type of the array is DINT.
The Average variable is a read and write direct variable associated with the Average database item (which is a variable double database item). The data type for the average variable is LREAL.
An internal variable, SUM, is used to store the result of the average calculation in the program. The SUM variable is of the data type DINT.
The code for calculating the average value and writing it to the Average variable double database item is:
Sum := 0;
FOR I := 0 TO Values.Length -1 DO
Sum := Sum+Values.Value[I];
END_FOR;
Average := DINT_TO_LREAL (Sum) /DINT_TO_LREAL (Values.Length);
So the program starts by initializing the Sum value to 0. The internal variable I is used to represent the index numbers of the elements in the array (each array element can contain a value, for example, the first element in an array has an index number of 0 and can contain one value; the second element has an index number of 1 and can contain one value and so on). The total number of array elements is defined by the Length value of the Values variable (the Values variable is a direct variable that represents the Values array database item). So, for the array elements with index numbers between 0 and the Length amount minus 1, the ST program will perform the calculation:
Sum := Sum+Values.Value[I];
When the ST program has read the values from the Values array, it calculates the average which is the Sum value divided by the Length value of the vector. The result of this calculation is stored in the Average variable database item.
Let's assume that the Values array database item has 5 values (stored in its 5 elements). When the ST program runs, it first initializes the Sum value at 0 and then begins to read the values in the array. It begins by reading the value from the array element with index number 0. This value is stored in the internal variable, Sum. The ST program then reads the value from the array element with index number 1 and adds the value to the Sum value. This is repeated until the ST program has read the values from the array elements with index numbers 0, 1, 2, 3, and 4. Although the ST program can read up to 100 elements ([0..99]), it can read fewer elements as required; it does not have to read 100 elements.
When the ST program has read the five array elements in the Values array database item, it calculates the average value. To do this, it divides the Sum amount by the Length value of the Vector. The result of this calculation is written to the Average variable database item.
Example 2 - Using a Vector to Write to an Array
In this example, the VECTOR keyword is used to allow an ST program to calculate new values and write them to an array database item.
PROGRAM NewStructuredTextProgram
VAR
Fib AT %M(.Fibonacci Sequence) : VECTOR[0..99] OF UDINT;
END_VAR
IF Fib.Length = 0 THEN
Fib.Value[0] := 0;
Fib.Length := 1;
ELSIF Fib.Length = 1 THEN
Fib.Value[1] := 1;
FIb.Length := 2;
ELSIF Fib.Length <99 THEN
Fib.Value[Fib.Length] := Fib.Value[Fib.Length - 1] + Fib.Value[Fib.Length - 2];
END_IF
In the VAR list, a single variable is defined. The variable is named Fib and it is a direct variable to the database item named Fibonacci Sequence (which is a variable array database item). The variable is defined as a VECTOR with a capacity of 100 values ([0 to 99]) and is of the data type UDINT.
The first part of the IF statement declares that if the length of the vector is 0, then the value in the array element with index number 0 is set to 0, and the length of the vector is changed to 1.
The second part of the IF statement declares that if the length of the vector is 1, then the value in the array element with index number 1 is set to 1, and the length of the vector is changed to 2.
The final part of the IF statement only applies if the length of the vector is between 2 and 99. If the length is between 2 and 99, the value for that element is the value of the previous element plus the value of the element before that, and the vector length is increased by 1.
So, if the Fibonacci Sequence array item contains no values, when the ST program first runs it will set the number of values the array can contain to 1 and will set the value for the only element in the array to 0.
The next time the ST program is executed, it will detect that the Fibonacci Sequence array item contains a single value and so the vector has a length of 1. This means that the ST program will increase the number of array elements to 2. The element with index number 0 will contain the 0 that was already in the array and the element with index number 1 will contain a new value defined by the ST program, in this case, 1.
The next time the ST program is executed, it will detect that the Fibonacci Sequence array item contains two values and that the vector has a length of 2. The ST program will increase the length of the vector by one to accommodate a new value and will then calculate the new value. The new value is the total of the previous two values stored in the array. In this case, the previous two values are 0 and 1 and so the new value is 1. The new value is stored in the element with index number 2.
The next time the ST program is executed, it will detect that the Fibonacci Sequence array item contains three values and that the vector has a length of 3. The ST program will increase the length of the vector by one to accommodate a new value and will then calculate the new value. The new value is the total of the previous two values stored in the array. In this case, the previous two values are 1 and 1 and so the new value is 2. The new value is stored in the element with index number 3.
Each time the ST program is executed, it will increase the length of the vector by 1 and calculate a new value. When the length of the vector is 99 (and so there are 100 values in the array), the ST program will no longer create new values or increase the length of the vector.
Example 3 - Using Vectors with Methods that Require Values in an Array
In this example, a vector is used to read the values from an array variable database item. The values that are read are used as the values for the SetForecast method on a Forecast database item.
PROGRAM NewStructuredTextProgram
VAR
V AT %M(.Values) : VECTOR[0..99] OF DINT;
END_VAR
METHOD
SFA AT %M(.Forecast (Array).SetForecast) : STRING, DT, ARRAY OF DINT;
SFV AT %M(.Forecast (Vector).SetForecast) : STRING, DT, VECTOR OF DINT;
END_METHOD
SFA( 'Test', NOW(), V.Value );
SFV( 'Test', NOW(), V );
END_PROGRAM
The V variable is defined as a direct variable that references a Long Array variable database item named 'Values'. As the variable is a direct variable, the Vector keyword is used (the Vector keyword has to be used for reading from an array in the database). The range of the Vector is defined as 0-99, as this is the capacity of the vector and the data type is defined as DINT.
The ST program calls two methods—the Set Forecast method on a Forecast database item named 'Forecast (Array)' and the Set Forecast method on a Forecast database item named 'Forecast (Vector)'. Each method requires three types of value: a string, a date-time, and an array.
For the 'Forecast (Array)' item's Set Forecast method (defined as SFA in the program), the program declares that the array value is an ARRAY OF DINT. This means that the Set Forecast method will use the values in the specified array (in this case, the values in the array for the vector, as defined later in the program by the V.Value entry). As the range of the vector is defined as 0..99, it means the SFA method will use 100 values.
For the 'Forecast (Vector)' item's Set Forecast method (defined as SFV in the program), the program declares that the array value is a VECTOR OF DINT. This means that the Set Forecast method will only use the amount of array values specified by the vector's Length property. So, if the vector's length is 10, the Set Forecast will only use the first ten values from the vector's array (the source of the vector's array is an array in the database, such as an array variable database item).
The SFA and SFV parts of the ST Program define the values for the methods.
For the SFA method (the Set Forecast method for the 'Forecast (Array)' database item), the string value is 'Test', the date-time value is NOW(), and the source of the array is V.Value. This means that the array values that are to be used for the method are those defined as the Value property of the V variable (which, in this program, is the vector). The value property of the V variable is the array referenced by the vector - the 'Values' array database item.
For the SFV method (the Set Forecast method for the 'Forecast (Vector)' database item), the string value is 'Test', the date-time value is NOW(), and the source of the array is V. This means that the vector is used as the source of the array values (v is the variable that represents the vector in the program). The length property of the vector determines how many array values are used and the value property of the vector is the source of the array values. So if the Length of the vector is 10, the SFV method will only use the first ten values in the'Values' array item (the 'Values' array item is the source of the vector's array).