This function allows you to tabulate values from a specific section of trend. The values in the table (possibly an array variable) are arranged by time.
If the period (Period) is different to the trend's sampling period (configured in the Trend Tags database), the returned values are determined by DisplayMode.
This function is a blocking function. It will block the calling Cicode task until the operation is complete.
Syntax
TrnGetTable(Tag, Time, Period, Length, Table, DisplayMode, Milliseconds [, sClusterName] )
Tag:
The trend tag enclosed in quotation marks "" (can be prefixed by the name of the cluster that is ClusterName.Tag).
Time:
The end time and date (long integer) of the desired trend section. Once you have entered the end time and date (Time), period (Period), and number of trend tag values collected (Length), the start time and date will be calculated automatically. For example, if Time = StrToDate("18/12/96") + StrToTime("09:00"), Period = 30, and Length = 60, the start time would be 08:30. In other words, the trend values for the period between 8.30am and 9am (on December 18, 1996) would be tabulated.
If this argument is set to 0 (zero), the time used will be the current time.
Period:
The time difference between tabulated trend values (in seconds). For example, if you set this period to 30 seconds, Citect SCADA will get the last trend value (sampled at the end of the trend section), then get the trend value that was sampled 30 seconds before that, and so on until it reaches the start time of the trend section.
If this period is different to the trend's sampling period, the trend values will be averaged or interpolated. Set to 0 (zero) to default to the actual trend period.
Length:
The number of trend values to store in the trend table, from 1 to the maximum number of items in the table. This argument has a max of 4000 (in v6). Specifying a length of greater than 4000 results in a return value of 0 and IsError()=274 (INVALID_ARGUMENT). This limit can be configured using the citect.ini parameter [Trend]MaxRequestLength.
Table:
Variable containing the Cicode array in which the trend data is stored. You can enter the name of an array here (see the example).
DisplayMode:
The Display Mode parameters allow you to enter a single integer to specify the display options for a trend (for a maximum of eight trends).
To calculate the integer that you should enter for a particular trend, select the options you want to use from those listed below, adding their associated numbers together. The resulting integer is the DisplayMode parameter for that trend.
Invalid/Gated trend options:
0 - Convert invalid/gated trend samples to zero.
1 - Leave invalid/gated trend samples as they are.
Ordering trend sample options:
0 - Order returned trend samples from oldest to newest.
2 - Order returned trend samples from newest to oldest.
Condense method options:
0 - Set the condense method to use the mean of the samples.
4 - Set the condense method to use the minimum of the samples.
8 - Set the condense method to use the maximum of the samples.
12 - Set the condense method to use the newest of the samples.
Stretch method options:
0 - Set the stretch method to step.
128 - Set the stretch method to use a ratio.
256 - Set the stretch method to use raw samples.
Gap Fill Constant option:
n - the number of missed samples that the user wants to gap fill) x 4096.
Options listed in each group are mutually exclusive. The default value for each Display Mode is 258 (0 + 2 + 256).
Milliseconds:
This argument allows you to set your sample request time with millisecond precision. After defining the time and date in seconds with the Time argument, you can then use this argument to define the milliseconds component of the time.
For example, if you wanted to request data from the 18/12/96, at 9am, 13 seconds, and 250 milliseconds you could set the Time and Milliseconds arguments as follows:
Time = StrToDate("18/12/96") + StrToTime("09:00:13")
Milliseconds = 250
If you don't enter a Milliseconds value, it defaults to 0 (zero). There is no range constraint, but as there are only 1000 milliseconds in a second, you should keep your entry between 0 (zero) and 999.
sClusterName:
Name of the cluster in which the trend tag resides. This is optional if you have one cluster or are resolving the trend via the current cluster context. The argument is enclosed in quotation marks "".
Return Value
The actual number of samples read. 0(zero) is returned if an error occurs. You can call the IsError() function to get the actual error code.
Related Functions
TrnSetTable, TrnGetDisplayMode
Example
REAL TrendTable1[100];
/* Defines an array of a maximum of 100 entries in which the trend data is stored. */
TrnGetTable("OP1",StrToDate("18/12/91") +StrToTime("09:00"),2,10,TrendTable1[0],0, "ClusterXYZ");
/* Stores the values of trend tag "OP1" in Table TrendTable1. Data is stored at the following times:
18/12/91 09:00:00 TrendTable1[0]
08:59:58 TrendTable1[1]
08:59:56 TrendTable1[2]
... 18/12/91 08:59:42 TrendTable1[9] */
Average=TableMath(TrendTable1[0],100,2);
/* Gets the average of the trend data. */
See Also
Published June 2018