See alsoExport and import of historic trend data. Selection of primary and secondary archive units.
WebVue support - Yes.
The instruction is not routed to the station that produces the archive unit. As a consequence, in a WebVue session context this instruction is processed by the computer that hosts the web back end and therefore will be effective only for archive units produced by that computer.
|
Mode |
Mnemonic |
Syntax |
| 1 | GETTREND | 1 |
| 2 | IMPORTTREND | 2 |
| 3 | UNIT | 3, 4, 5, 11, 12 |
| 4 | TREND | 6, 7, 8, 9, 10, 13 |
Syntax 1
LVAL = HISTORY (Mode, VarName, TimeStart, TimeEnd, FileName [,FileMode[, Format[, StateVar[, NbVar]]]]);
Return type: LONG.
|
Argument |
Meaning |
|
VarName |
The name of a variable for which the historic data is to be exported. Type STR. |
|
TimeStart |
The time and date for selection of the earliest data to be exported. Type DOUBLE. See instruction DATETIMEVALUE for the conversion of time and date. |
|
TimeEnd |
The time and date for selection of the latest data to be exported. Type DOUBLE. See instruction DATETIMEVALUE for the conversion of time and date. |
|
FileName |
The name of the file into which the data is exported. Type STR. If executed in a WebVue session context this instruction is processed by the computer that hosts the web back end and the referenced file is on that computer. |
|
FileMode |
The mode in which the file will be used. 0 creates the file, overwriting any previous versions (default value). 1 opens the file, and appends data to the end. |
|
Format |
A string defining the format in which the historic data will be exported. The following format elements may be used : |
|
Element |
Description |
|
###Y |
The year as 4 digits (example : 1994) |
|
#Y |
The year as 2 digits (example : 94) |
|
#M |
The month (01 to 12) |
|
#D |
The day (01 to 31) |
|
#h |
The hours (00 to 23) |
|
#m |
The minutes (00 to 59) |
|
#s |
The seconds (00 to 59) |
|
##l |
The milliseconds (000 to 999) |
|
#V |
The value of the variable |
|
|
If Format is omitted or is a null string, the default format of #Y#M#D#h#m#s##l, #V will be used. |
|
StateVar |
The name of a bit variable. When the export is started the bit is initialized to 0. At the end of the export, the bit is set to 1. This allows a function to be activated at end of an export (see EVENT). If this facility is not required, the name of the variable may be replaced with a null string. Type STR. |
|
NbVar |
The name of a register variable. At the end of an export, it will contain the number of values exported. If this facility is not required the name of the variable may be replaced with a null string. Type STR. |
Execution
|
Mode |
Mnemonic |
Action |
|
1 |
GETTREND |
Export of the historic record of a variable's value. Return: 0 if error, any other number OK. |
Syntax 2
LVAL = HISTORY (Mode, FileName[, StateVar [, NbVar[, FORMAT [,VARNAME]]]]);
Return type: LONG.
|
Argument |
Meaning |
|
FileName |
The name of the file containing the data to be imported. Type STR. If executed in a WebVue session context this instruction is processed by the computer that hosts the web back end and the referenced file is on that computer. |
|
StateVar |
The name of a bit variable. When the import is started the bit is initialized to 0. At the end of the import, the bit is set to 1. This allows a function to be activated at the end of an import (see EVENT). If this facility is not required, the name of the variable may be replaced with a null string. Type STR. |
|
NbVar |
The name of a register variable. At the end of an import, it will contain the number of values imported. If this facility is not required, the name of the variable may be replaced with a null string. Type STR. |
|
FORMAT |
A string describing the expected format of data in the import file. If not supplied then the format must be specified in the import file itself. Type STR. |
|
VARNAME |
A string defining the name of the variable for which the historic data is to be imported. If not supplied, the variable names must be specified in the import file itself. Type STR. |
Syntax of the Format String
The format string may be used either as part of the History instruction, or as a line in the import file itself. The syntax is as follows:
FORMAT,Msflag,VarFlag,TSFormat
|
Format String |
Meaning |
|
MsFlag |
A flag indicating if milliseconds are used in the timestamp: 0 Milliseconds not used. 1 Milliseconds used. |
|
VarFlag |
A flag that specifying if the name of the variable is present on each line of the data in the import file: 0 No variable identifier. 1 The variable identifier is the variable name. 2 The variable identifier is the variable's internal ID. |
|
TSFormat |
The format of the timestamp in the import file. 0 YYMMDDhhmmss[ms] |
Syntax of the VARNAME String
The VARNAME string may be used either as part of the History instruction, or as a line in the import file itself. The syntax is as follows:
VARNAME,Varname
|
Argument |
Meaning |
|
VarName |
The name of the variable for which the historic data is to be imported. |
The Import File Format
The import file must be in ASCII format with each line being a comment, keyword or data.
Any line preceded by a single quotation mark (') or a hash (#) is treated as a comment and is not processed.
Any line starting with FORMAT is treated as a format string (see above).
Any line starting with VARNAME is treated as variable definition (see above).
All other lines are treated as data and must conform to the following syntax:
TimeStamp,Value[,Varname]
|
Data |
Meaning |
|
TimeStamp |
The timestamp in the selected format. |
|
Value |
The value of the variable at that time. |
|
VarName |
The name of the variable for this line. |
Execution
|
Mode |
Mnemonic |
Action |
|
2 |
IMPORTTREND |
Import of historic values for a variable. To enable this, the check box Import Data File must be selected in the variable's configuration. |
|
|
|
Return: 0 if error, any other number OK. |
Syntax 3
LVAL = HISTORY (Mode, UnitName, Operation);
Return type: LONG.
|
Argument |
Meaning |
|
UnitName |
The name of an archive unit. Type STR. |
|
Operation |
A string to select the type of operation. Type STR. |
Execution
|
Mode |
Mnemonic |
Action |
|
3 |
UNIT
|
Manipulation of the named archive unit. The string contained in the parameter Operation determines the action: |
|
|
Flush |
Write (flush) the contents of all memory buffers to the archive unit files. Return: 0 if error, any other number OK. |
|
|
Next |
Continue recording in the next file in the sequence (proprietary and free format archive units). Return: 0 if error, any other number OK. |
|
|
Enable |
Enable recording in the archive unit (only free format archive units). Return: 0 if error, any other number OK. |
|
|
Disable |
Disable recording in the archive unit (only free format archive units). Return: 0 if error, any other number OK. |
|
|
Isreadonly |
Check the read only property of the archive unit (proprietary and free format archive units). Return: -1 if error, 1 if read only, else 0. |
|
|
Lock |
Temporarily inhibit the archive unit Return: 0 if error, any other number OK. |
|
|
Unlock |
End a temporary inhibit applied to an archive unit using 'LOCK' Return: 0 if error, any other number OK. |
Syntax 4
LVAL = HISTORY (Mode, UnitName, "READONLY", Flag);
Return type: LONG.
|
Argument |
Meaning |
|
UnitName |
The name of an archive unit. Type STR. |
|
Flag |
A flag to change the read-only property of the archive unit. Any numeric type. |
Execution
|
Mode |
Mnemonic |
Action |
|
3 |
UNIT |
Change the read-only property of the archive unit. If the flag is 0 then the read-only property is disabled (you can write to the archive unit). If the flag is 1 then the read-only property is enabled. |
Syntax 5
LVAL = HISTORY (Mode, UnitName, Operation [, StateVar, Flag]);
Return type: LONG.
|
Argument |
Meaning |
|
UnitName |
The name of an archive unit. Type STR. |
|
Operation |
A string to select the type of operation. Type STR. |
|
StateVar |
The name of a bit variable. Type STR. |
|
Flag |
A flag (0 or 1) |
Execution
|
Mode |
Mnemonic |
Action |
|
3 |
UNIT |
Manipulation of the named archive unit. The string contained in the parameter "Operation" determines the action. See syntax 3 for details. The bit variable StateVar will be set to the value of the flag when the operation is complete. |
Syntax 6
LVAL = HISTORY (Mode, "SETPRIMARY", VarName, UnitName);
Return type: LONG.
|
Argument |
Meaning |
|
VarName |
The name of a variable that has been configured to record trend data using two or more archive units. Type STR. |
|
UnitName |
The name of one of the secondary archive units for the named variable. Type STR. |
Execution
|
Mode |
Mnemonic |
Action |
|
4 |
TREND |
Selects one of the secondary archive units for a variable configured to record data in more than one archive units. When PcVue extracts data for this variable (for use in a Trend Viewer for example), the data is taken from the secondary archive unit. |
|
|
|
Return: 0 if error, else OK. |
This is a temporary change and is not saved when PcVue is shut down. On starting again, it uses the original configuration.
Syntax 7
LVAL = HISTORY (Mode, "CLEARPRIMARY", VarName;
Return type: LONG.
|
Argument |
Meaning |
|
VarName |
The name of a variable that has been configured to record trend data using two or more archive units. Type STR. |
Execution
|
Mode |
Mnemonic |
Action |
|
4 |
TREND |
Selects the primary unit from after changes of assignment by script (sub mode SETPRIMARY). The sub mode CLEARPRIMARY re-assigns as primary unit the one configured as such. When PcVue extracts data for this variable (for use in a trend display for example), the data is taken from the primary archive unit. |
|
|
|
Return: 0 if error, else OK. |
Syntax 8
LVAL = HISTORY (Mode, "SETPRIMARY_UNIT", PrimaryUnit, SecondaryUnit);
Return type: LONG.
|
Argument |
Meaning |
|
PrimaryUnit |
The name of the primary archive unit. Type STR. |
|
SecondaryUnit |
The name of a secondary archive unit. Type STR. |
Execution
|
Mode |
Mnemonic |
Action |
|
4 |
TREND |
Selects one of the secondary archive units for all variables having the named primary and secondary archive units. When PcVue extracts data for any of these variables (for use in a Trend Viewer for example), the data is taken from the secondary archive unit. |
|
|
|
Return: 0 if error, else OK. |
This is a temporary change and is not saved when PcVue is shut down. On starting again, it uses the original configuration.
Syntax 9
LVAL = HISTORY (Mode, "CLEARPRIMARY_UNIT", PrimaryUnit);
Return type: LONG.
|
Argument |
Meaning |
|
PrimaryUnit |
The name of the primary archive unit. Type STR. |
Execution
|
Mode |
Mnemonic |
Action |
|
4 |
TREND |
Selects the primary unit after changes of assignment by script (sub mode SETPRIMARY_UNIT). The sub mode CLEARPRIMARY_UNIT re-assigns as primary unit the one configured as such. When PcVue extracts data for this variable (for use in a Trend Viewer for example), the data is taken from the primary archive unit. |
|
|
|
Return: 0 if error, else OK. |
Syntax 10
LVAL = HISTORY (Mode, "SAMPLING", VarName, UnitName, SampleRate);
Return type: LONG.
|
Argument |
Meaning |
|
VarName |
The name of a variable that has been configured to record trend data. Type STR. |
|
UnitName |
The name of one of the archive units for the named variable. Type STR. |
|
SampleRate |
A period from 0 to 32000 seconds. |
Execution
|
Mode |
Mnemonic |
Action |
|
4 |
TREND |
Allows the sample rate for recording data for the named variable and archive unit to be dynamically changed. |
|
|
|
Return: 0 if error, else OK. |
This is a temporary change and is not saved when PcVue is shut down. On starting again, it uses the original configuration.
Syntax 11
LVAL = HISTORY (Mode, UnitName, Sub-mode, ServerName);
Return type: LONG.
|
Argument |
Meaning |
|
UnitName |
The name of the archive unit that is to be redirected. Type STR. |
|
ServerName |
Name of the station to which the local station's access requests are to be directed. The station must be part of a historical server association. |
Execution
|
Mode |
Mnemonic |
Sub-mode |
Mnemonic |
Action |
|
3 |
UNIT |
10 |
SETREADSERVER |
Dynamically configure which of the two stations in an historic association a historic client reads from. |
|
|
|
|
|
Return: 0 if error, 1 if OK. |
This is a temporary change and is not saved when PcVue is shut down. On starting again, it uses the original configuration.
If a client station makes a request to read from server station 1 which itself is redirected to server station 2, the client station's request will be handled by server station 2.
It is vital to understand the mechanism for redirecting read requests to avoid configurations that loop.
For example, where server 1 is redirected to server 2 which itself is redirected to server 1.
Syntax 12
LVAL = HISTORY (Mode, UnitName, Sub-mode, RestoreReadServer);
Return type: LONG.
|
Argument |
Meaning |
|
UnitName |
The name of the archive unit that is to be restored. Type STR. |
Execution
|
Mode |
Mnemonic |
Sub-mode |
Mnemonic |
Action |
|
3 |
UNIT |
11 |
RESTOREREADSERVER |
Restore the archive unit's original configuration. |
|
|
|
|
|
Return: 0 if error, 1 if OK. |
Syntax 13
LVAL = HISTORY (Mode, "FORCEPRIMARY_UNIT", PrimaryUnit);
Return type: LONG.
|
Argument |
Meaning |
|
PrimaryUnit |
The name of the archive unit to which the historical data is recorded. Type STR. |
Execution
|
Mode |
Mnemonic |
Sub-mode |
Mnemonic |
Action |
|
4 |
TREND |
- |
FORCEPRIMARY_UNIT |
Specifies the primary archive unit for reading. |
|
|
|
|
|
Return: 0 if error, 1 if OK. |
Changes are not saved when PcVue closes. On starting again, it uses the original configuration.
Using SETPRIMARY_UNIT/SETPRIMARY and FORCEPRIMARY
These enable choice from a client station of the unit that is to be used on a server.
With PcVue version 8.10 onwards, when there is a Trend request between stations the primary unit's name is transmitted to the producer of the historical data.
Example
For an example, select the Example link above.