EXPORT_TREND

Concept Link IconSee also Concept Link IconExample

Generate historic trend data using the functionality provided by Data Export. See the main Data Export help for details (the Application Explorer.Data Export). See also the important Operational Notes below.

WebVue support - Yes.

The use of the verbs EXPORT, EXPORT_LOG and EXPORT_TREND is preferred to verbs SVLOG and SVTREND. The latter are kept for compatibility only.

The Data Export module is protected by a license option in PcVue's protection key. If you do not have this option then Data Export will only operate in demonstration mode.

Mode Mnemonic Syntax
1 GETRAW 1
2 GETSAMPLE 2
3 GETSTATISTIC 3
4 GETAGGREGATED 4
5 READBUFFER 5
6 CANCEL 6
7 DISPOSE 6

Common Arguments

Argument

Meaning
ListVariables

The list of variables for which to request historic data, as either a string or a pointer to a buffer containing the string. Type STR or DOUBLE.
Branch A branch that will be prefixed to all variable names. Type STR;
Unit The name of the archive unit that contains the historic data. If left empty then the primary archive unit for each variable is used. Type STR.
StartTime The start time for the historic request. The start time must be earlier than the end time. Type DOUBLE.
EndTime The end time for the historic request. The end time must be later than the start time. Type DOUBLE.
StatusVariable The name of a register variable in which the status of the export is reported. Type STR.
LineSeparator A single character that is to be used as a line separator in the request output. Type STR.
Using "\n" (carriage return) is recommended to avoid parsing errors due to regional settings or field values (those may have commas, semi-columns or dots).
ColumnSeparator A single character that is to be used as a column separator in the request output. Type STR.
Using "\t" (tab) is recommended to avoid parsing errors due to regional settings or field values (those may have commas, semi-columns or dots).
MaxRetLines The maximum number of lines that the request returns (overrides the global setting Max count for generated data). 0 = no maximum. Type INTEGER.
MaxValuesToProcess The maximum number of raw values that are to be processed (overrides the global setting Max count for raw data). 0 = no maximum. Type INTEGER.
TimeStampsFormat The format of the timestamp. 0 = date and time, 1 = date only, 2 = time only. Optional with 0 as the default.

Syntax 1

IntVal = EXPORT_TREND(Mode, VariableName, Branch, Unit, StartTime, EndTime, StatusVariable, LineSeparator, ColumnSeparator, MaxRetLines[, TimeStampsFormat]);

Return type: INTEGER.

Argument

Meaning
VariableName

The variable from which to collect historic data. Type STR.

Execution

Mode

Mnemonic

Action
1 GETRAW

Generate a historic request to return the raw values for a single variable.
Return: See the Operational Notes below.

Syntax 2

IntVal = EXPORT_TREND(Mode, ListVariables, Branch, Unit, StartTime, EndTime, StatusVariable, LineSeparator, ColumnSeparator, MaxValuesToProcess, MaxRetLines, SamplingRateInterval, SamplingRateValue [,SynchroSecondValue, SynchroMinuteValue, SynchroHourValue, SynchroDayValue, SynchroMonthValue, TimeStampsFormat]);

Return type: INTEGER.

Argument

Meaning
SamplingRateInterval The sample rate unit. Type INTEGER.
0 = Seconds
1 = Minutes
2 = Hours
3 = Days
4 = Weeks
5 = Months
6 = Years
SamplingRateValue The sampling rate value. Type INTEGER.

SynchroSecondValue
SynchroMinuteValue
SynchroHourValue
SynchroDayValue
SynchroMonthValue

Equivalent to the Synchronization Time and Day properties in the Data Export Sampling tab. See the main Data Export help for details (the Application Explorer.Data Export). Type INTEGER.

Execution

Mode

Mnemonic

Action
2 GETSAMPLE

Generate a historic request to return sampled value for the variables list.

Return: See the Operational Notes below.

Syntax 3

IntVal = EXPORT_TREND (Mode, ListVariables, Branch, Unit, StartTime, EndTime, StatusVariable, LineSeparator, ColumnSeparator, MaxValuesToProcess, MaxRetLines, StatFlag);

Return type: INTEGER.

Argument

Meaning
StatFlag

A number calculated using binary weighted values, representing the statistics to generate (decimal values in brackets). Type DOUBLE.
0x0001 = Min (1)
0x0002 = Max (2)
0x0004 = Average (4)
0x0008 = Sum (8)
0x0010 = Standard deviation (16)
0x0020 = First value (32)
0x0040 = Last value (64)
0x0080 = Counter (128)
0x0100 = Min date (256)
0x0200 = Max date (512)
0x0400 = First value date (1024)
0x0800 = Last value date (2048)
0x1000 = Weighted average (4096)

Execution

Mode

Mnemonic

Action
3 GETSTATISTIC

Generate a historic request to return statistical values for the variables list.

Return: See the Operational Notes below.

Syntax 4

IntVal = EXPORT_TREND(Mode, ListVariables, Branch, Unit, StartTime, EndTime, StatusVariable, LineSeparator, ColumnSeparator, MaxValuesToProcess, MaxRetLines, StatFlag, SamplingRateInterval, SamplingRateValue [,SynchroSecondValue, SynchroMinuteValue, SynchroHourValue, SynchroDayValue, SynchroMonthValue, TimeStampsFormat, TimeStampsFields]);

Return type: INTEGER.

Argument

Meaning
TimeStampsFields

A number indicating the timestamp fields to use. Type INTEGER.

0 = Beginning timestamp. The default if TimeStampFields is not used.
1 = End timestamp only.
2 = Both beginning and end timestamps.

See Syntax 2 and Syntax 3 for a description of the arguments StatFlag, SamplingRateInterval, SamplingRateValue, SynchroSecondValue, SynchroMinuteValue, SynchroHourValue, SynchroDayValue and SynchroMonthValue.

Execution

Mode

Mnemonic

Action
4 GETAGGREGATED

Generate a historic request to return aggregated statistical values for the variables list.

Return: See the Operational Notes below.

Syntax 5

IntVal = EXPORT_TREND(Mode, BufferHandle);

Return type: INTEGER.

Argument

Meaning
BufferHandle

The handle of a buffer previously created using ALLOC_BUFFER. Type LONG.

Execution

Mode

Mnemonic

Action
5 READBUFFER

Read the buffer of data after either a GETRAW, GETSAMPLED, GETSTATISTIC or GETAGGREGATED.
The status variable must be either 0 (completed), 4 (completed but the maximum number of points has been reached) or 5 (completed but the maximum number of processed values has been reached).
Return: The number of lines retrieved or if less than 1:
0 = End of buffer
-1 = Invalid buffer handle
-2 = No previous historic request has been sent
-3 = No answer received
-4 = Nothing to read
-5 = Buffer too small

Syntax 6

IntVal = EXPORT_TREND(Mode);

Return type: INTEGER.

Execution

Mode

Mnemonic

Action
6 CANCEL

Cancel the current historic request. A CANCEL should always be followed by a DISPOSE.
Return: Always 0
7 DISPOSE Release internal buffer used in a historical request. Must always be called before making a further historic request or after a CANCEL.
Return: Always 0

Operational Notes

The EXPORT_TREND instruction operates asynchronously. That is once a historical request has been generated by either modes GETRAW, GETSAMPLED, GETSTATISTIC or GETAGGREGATED, the script continues without waiting for the historical data to be generated. The instruction's return value indicates if the historic request was successfully sent, or not.

When the historical request is complete (successfully or otherwise) the value of the Status Variable is changed accordingly. On this change, if the Status Variable's value indicates a success, READBUFFER mode must be used to retrieve the data into a memory buffer from where further processing can be done (for example exporting to Excel using BUFTOEXCEL).

It will normally be necessary to use READBUFFER more than once until the number of lines it returns is 0 indicating that all data has been processed.

If you use a loop including READBUFFER, you must respect the 30 seconds limit that is allowed for a continuous SCADA Basic thread. If you exceed this (which is possible if you are processing large amounts of data), the thread will abort with an error.

After completion, a DISPOSE mode must be executed to release the internal buffer used in the historical request.

Return values

All return values other than zero indicate an error. In particular, -30 indicates a previous request is still running and should be accommodated in the script.

Value

Meaning
0 The historic request has been successfully sent.
-1 VariableName or ListVariable is of an incorrect type or cannot be read.
-2 Branch is of an incorrect type or cannot be read.
-3 UnitName is of an incorrect type or cannot be read.
-4 Branch plus VariableName does not exist.
-5 The variable, or one of the variables is not configured for trend recording.
-6 The StartTime is invalid or undefined.
-7 The EndTime is invalid or undefined.
-8 StatusVariable is not a string or the variable it names is not a register.
-9 LineSeparator cannot be read.
-10 ColumnSeparator cannot be read.
-20 StatFlag is not a double.
-21 SamplingRateInterval is not an integer.
-22 SamplingRateValue is not an integer.
-23 Synchronize parameter is not valid.
-30 A previous historic request is still running.

Status variable values

The status of the latest historical request.

Value

Meaning
0 Completed successfully.
1 Running.
3 Canceled.
4 Completed but the maximum number of points has been reached.
5 Completed but the maximum number of processed values has been reached.
10 Failed.
11 Failed due to an incorrect configuration.
12 Failed due to a failed historical request.

Examples

See the Examples link at the top of the topic.