HST2TXT

HST2TXT exports historical data from the trend history files (*.hst) to a plain text file (*.txt).

Syntax

HST2TXT(strStartDate,strStartTime,numDuration,numGroup,strTargetFile,optStrSeparator,optNumMilliseconds,optStrFormat,optNumInterval)

strStartDate

The start date (for example, 04/14/2002) of the data to be exported. The date must be in the format used by the project runtime server. For more information, see Notes below.

strStartTime

The start time (for example, 06:30:00) of the data to be exported.

numDuration

The duration (in hours) of the data to be exported, starting from the specified start date and time.

numGroup

The trend group or worksheet number. For more information, see Trend worksheet.

strTargetFile

The name of the text file to which the data will be exported.

By default, the file must be located in your project folder (that is, the folder that contains the file <project name>.app), on the computer that hosts the project runtime server. If the file is or should be located in another folder, specify the complete file path.

Note: Follow the conventions of the target platform for the file path and name, and separators. For example, a file path in Windows starts with a drive letter and uses backward slashes as separators (C:\path\to\file), while a file path in Linux starts at the root directory and uses forward slashes as separators (/path/to/file).

optStrSeparator

The character that will be used to separate the values in each line of the file.

This parameter is optional; if no value is specified, the default value is a TAB character (\t).

optNumMilliseconds

A numeric flag that indicates whether to show millisecond-precision in the timestamp on each entry:

This parameter is optional; if no value is specified, the default value is 0.

optStrFormat

The date format that will be used in the timestamp on each entry:

This parameter is optional; if no value is specified, the default value is DMY.

optNumInterval

The interval between entries to be exported. Only entries at this interval are exported to the specified file. For example, if optNumInterval is 10, only every tenth entry is exported.

This parameter is optional; if no value is specified, every entry is exported.

Returned value

This function returns one of the following possible values:

Notes

If a Trend group/worksheet is configured to save historical data to proprietary history files instead of an external database, the files will be saved in your project folder at <project name>\Hst\*.hst, on the computer that hosts your project runtime server. These history files are in a proprietary binary format, which is why it is necessary to export the historical data to a separate text file if you want to reuse your trend history in other applications.

Since the history files are located on the server, the export must be done on the server, which means this function is executed on the server even when it is called in a project screen on a thin client. You cannot export to a file on the thin client.

Furthermore, since this function is executed on the server, the date that you specify for strStartDate must be in the date format used by the server. If you specify a date in a different date format — even the format used by the client — the server will not recognize it and this function will return a value of -4 (that is, invalid date format). For more information, see About the date format and how to change it.

Although this function can be called while the project is either running or stopped, it can be executed only after the project has run at least once. If you try to call this function before the project has ran — for example, if you start the Edge HMI application and then immediately enter this function in the Watch window — it will fail without error.

If you want to export historical data without running the project, you can also use the command-line utility HST2TXT.exe. It is especially useful if you want to do the export as part of a longer, scripted procedure. For more information, see Converting Trend History Files from Binary to Text.

Tip: To export to a comma-separated values (CSV) file that can be imported into Microsoft Excel and other spreadsheet applications, specify a comma separator and a file name with the CSV suffix (for example, history.csv).

Examples

Export 0.1 hour (that is, six minutes) of historical data from Trend group/worksheet 3 to a slash-separated text file:

HST2TXT("04/14/2002","06:30:00",0.1,3,"data.txt","\")

Export 0.1 hour (that is, six minutes) of historical data from Trend group/worksheet 3 to a CSV file using the MDY date format:

HST2TXT("04/14/2002","06:30:00",0.1,3,"data.csv",",",0,"MDY")

Export every tenth entry in 0.1 hour (that is, six minutes) of historical data from Trend group/worksheet 3 to a CSV file using the MDY date format:

HST2TXT("04/14/2002","06:30:00",0.1,3,"data.csv",",",0,"MDY",10)