Script Custom Reports

Scripting custom reports originated before the existence of the Report Studio. Before scripting your own custom report, familiarize yourself with The Report Studio There may be a native solution.
The Report Studio allows you to create custom report through a user interface.
Reports made in the Report Studio work with the Report tag and can be triggered by schedule, event, widget or ad hoc from the studio.
Additional calculations and post processing of data is possible using features such as the Calculations Data Set.
Using the Report Studio does not require any knowledge of the VTScada scripting language. Reports are very flexible and fully supported.

The Reports Page will continue to be supported.

You can build your own custom reports that integrate into the VTScada Report Page or Report Tag, and therefore make use of the VTScada Report Page's features such as selection of tags, start and end dates, output formats, etc. Your module can control the data retrieval process, defining what is retrieved and what further calculations are done on the returned values.

Report Formatting

Writing VTScada code for more complex formatting is not recommended. If a fancy report appearance is required, you can copy the default output into a document or spreadsheet and apply fonts, colors, cell borders, sub-total breaks, and other features there. Macros in programs such as Excel can help automate this process if it needs to be done on a repeating basis.

By following this approach, you ensure that your reports remain flexible for use with a variety of output formats.

Limiting the List of Available Tags

By declaring a constant named "TypeFilter" you can limit the range of tags available to the user for selection in the VTScada Reports Page. Possible values include any tag name or group. Because only logged data is available to be reported on, it is common to set this to "Loggers" but for your report it may be appropriate to limit the selection to "Pump Status" or "Digitals".

Example:

Constant TypeFilter = "Loggers";

Parameters in a Custom Report

A minimum of four parameters should be declared in your module. In addition to the VTScada Reporter object, these allow user-selected parameters from the VTScada Report Page to be passed to your custom report. The standard parameters are as follows:

  • Reporter

Object value for call-backs.

  • Start

User-selected starting time.

  • End

User-selected ending time.

  • Tags

User-selected list of tag names to report on

In addition to these, you may decide to create a generic report that can be used for many variations. The values for these parameters will not come from the Report page, but from other reporting modules that you create to provide variations to your core report. Extra parameters may include:

  • Vars

List of logged variables within tags. This will always be "Value" when reporting on VTScada tags, but if your application contains custom tags with other logged variables, you may override this parameter to provide the variable name, or an array of logged variable names.

  • TimeRange

Time range in seconds for each data point retrieved by the query. Passed to the GetTagHistory function as the TPP parameter. Appropriate choices for this value will depend on the selected mode.

  • ReportName

For customized report naming.

  • Mode

The Mode to run GetTagHistory in, thereby changing how data is queried. Please see the following topic, Query Modes and Time Ranges.

  • StaleTime

Optional: used in Mode 11 (Rollover Totals). See GetTagHistory in the function reference for more details.

Common Features of a Report Module

All report modules must contain the following features:

  • Module structure follows VTScada coding rules.
  • Parameter list enables the Report Page to pass user selections in.
  • Shared reference to Report so that the module becomes a plug-in of the Report Page.

Variables include:

  • TypeFilter - limits tag selection in the Report Page
  • ReportName - displayed Report Type in the Report Page
  • The initialization state sets the query parameters and writes the titles to the output stream for the report.
  • A second state calls GetTagHistory for each user-selected tag.
  • A third state processes the data, sending the rows to the VTScada report generator, then slays the module when finished.

These features can be seen in Example: Custom Snapshot Report. This module creates a snap-shot type report. Instead of collecting an hourly or daily snapshot, it retrieves the value at the start of each 15-minute data range.

You can add this report to any VTScada application by copying the code into a text file and declaring it in the AppRoot.SRC of the application. For example, if you named the file containing this module, "QuarterHour.src" declare it in the (PLUGINS) section of the AppRoot.SRC file as follows:

[(PLUGINS) 
    QuarterHour   Module   "QuarterHour.src";
]

Remember that file changes must always be imported before they come into effect.