TextDocFromHistoricData Function Block

Help Contents

Introduction

The TextDocFromHistoricData Function Block creates a TextDocument object from data stored in the Fernhill SCADA Historian.

Functions and Function Blocks

The TextDocFromHistoricData Function Block is intended for use in a Program Tag that runs on the Fernhill SCADA Server. A Program Tag uses a continuous execution model, where the program code runs at a fixed interval. A program uses this function block to sample the state of the Historical Data Query as it executes.

There is currently no equivalent TextDocFromHistoricData Function for use in an Operator Action.

Syntax

The TextDocFromHistoricData Function Block has this syntax:

TextDocFromHistoricData(
        REQ:=Expression,
        TAGNAMES:=Expression,
        STARTTIME:=Expression,
        ENDTIME:=Expression,
        SAMPLEINTERVAL:=Expression,
        SAMPLETYPE:=Expression,
        OUTPUTFORMAT:=Expression,
        BUSY=>Variable-Reference,
        DOCUMENTID=>Variable-Reference,
        DONE=>Variable-Reference,
        ERROR=>Variable-Reference,
        ERRORMSG=>Variable-Reference );

Note: All parameters are optional.

Parameters

Parameter Type Direction Description
REQ BOOL R_EDGE Input A rising edge triggers the reading of the historical data.
TAGNAMES ANY_STRING or ANY_INT Input The tag names to read the history from. The type of this parameter defines how the function block gets the tag names:
  • ANY_STRING - The parameter is a tag name. The function block reads the history of one tag.
  • ANY_INT - The parameter is the identifier of a Linked List Data Object. Each entry in the linked list is a tag name. The function block reads the history of each tag in the linked list.
STARTTIME ANY_DATE Input The start date and time of the history.
ENDTIME ANY_DATE Input The end date and time of the history.
SAMPLEINTERVAL TIME Input The interval between each historical data sample.
SAMPLETYPE ANY_STRING Input How to sample the data. These sample types are supported:
  • 'Average' - The average of the good values in the interval are returned.
  • 'Count' - The number of good values in the interval are returned.
  • 'Delta' - The difference between the first and last good values in the interval.
  • 'End' - The last good value in the interval is returned.
  • 'Interpolation' - A value at the start of each interval is interpolated from the first good value before and after.
  • 'Maximum' - The largest value in the interval is returned.
  • 'MaximumActualTime' - The largest value in the interval is returned with the timestamp of the value.
  • 'Minimum' - The smallest value in the interval is returned.
  • 'MinimumActualTime' - The smallest value in the interval is returned with the timestamp of the value.
  • 'Range' - The absolute difference between the minimum and maximum values is returned.
  • 'Start' - The first good value in the interval is returned.
OUTPUTFORMAT ANY_STRING Input The format of the generated text document. See Text Document Output Format for more information.
BUSY BOOL Output Set to TRUE while the configuration change is in progress.
DOCUMENTID UDINT Output The identifier of the TextDocument Object. Note: This value is only valid while the DONE output parameter is TRUE.
DONE BOOL Output Set to TRUE for 1 execution after the read of historical data has completed.
ERROR BOOL Output Set to TRUE if there was an error reading the historical data.
ERRORMSG WSTRING Output If ERROR is TRUE, the reason why the historical data read failed.

Remarks

Once the function block starts, additional requests from the input signal REQ are ignored until the configuration change completes.

These timing diagrams show the relationship of the REQ, BUSY, DONE, and ERROR signals processing two requests. The first request completes with an error, the second request completes normally:

        +--------+     +-+ +------+
  REQ   |        |     | | |      |
      --+        +-----+ +-+      +------

        +------+       +------+
 BUSY   |      |       |      |
      --+      +-------+      +----------

               ++             ++
 DONE          ||             ||
      ---------++-------------++---------

               +-------+
ERROR          |       |
      ---------+       +-----------------

The BUSY signal is TRUE while the configuration change is in progress. The DONE signal is TRUE for 1 execution after the completion of the configuration change.

The TextDocFromHistoricData Function Block is only available to IEC 61131-3 code in an IEC 61131-3 Program Tag.

Examples

  1. Read hour average values for a 1 day time interval from 1 data point tag:
    Program Main
    Var
        TextDoc : TextDocFromHistoricData;
        Trigger AT %"Trigger Tag" : BOOL;
        DocumentId : UDINT;
    End_Var
    
        TextDoc(
            REQ := Trigger,
            TAGNAMES := 'Analog Tag',
            STARTTIME := D#2022-11-01,
            ENDTIME := D#2022-11-02,
            SAMPLEINTERVAL := T#1h,
            SAMPLETYPE := 'Average',
            OUTPUTFORMAT := 'CSV' );
    
        IF TextDoc.DONE THEN
    
            IF TextDoc.ERROR THEN
    
                (* Handle the error *)
            ELSE
    
                (* Get the text document identifier *)
                DocumentId := TextDoc.DOCUMENTID;
                
                (* Process the data:
                    Use TextDocGetValue() to retrieve values from the Text Document.
                    Use TextDocWriteToUrl() to write the data to an external URL
                *)
    
            END_IF
        END_IF
    End_Program
    
  2. Read hour maximum values for a 1 day time interval for multiple tags:
    Program Main
    Var
        TextDoc : TextDocFromHistoricData;
        PushToUrl : TextDocWriteToUrl;
        Trigger AT %"Trigger Tag" : BOOL;
        TagNameList : UDINT;
        DocumentId : UDINT;
    End_Var
    
        TagNameList := LinkedListCreate();
        LinkedListAddLast( TagNameList, 'AnalogTag 1');
        LinkedListAddLast( TagNameList, 'AnalogTag 2');
        LinkedListAddLast( TagNameList, 'AnalogTag 3');
    
        TextDoc(
            REQ := Trigger,
            TAGNAMES := TagNameList,
            STARTTIME := D#2022-11-01,
            ENDTIME := D#2022-11-02,
            SAMPLEINTERVAL := T#1h,
            SAMPLETYPE := 'Average',
            OUTPUTFORMAT := 'JSON' );
    
        IF TextDoc.DONE AND TextDoc.ERROR THEN
    
            (* Report the error *)
    
        END_IF
    
        PushToUrl(
            REQ := TextDoc.DONE AND NOT TextDoc.ERROR,
            DOCUMENTID := TextDoc.DOCUMENTID,
            URL := 'ftp://ftp.example.com/uploads/historicdata.json',
            OPTIONS := '' );
    
    End_Program
    

Further Information

TextDocument Functions

For information about functions to manage TextDocument data objects.

LinkedList Data Object

To learn how to create and manage linked lists of values.

TextDocGetValue Function

To learn how to read values from a TextDocument.

TextDocWriteToUrl Function Block

To learn how to write TextDocument to a URL.

Data Objects

For information about all Data Objects supported by Fernhill SCADA.

IEC 61131-3

To learn how IEC 61131-3 is used in Fernhill SCADA.

Glossary

For the meaning of terms used in Fernhill SCADA.